Kong Services API

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 Services 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:
- description: 'Service entities are abstractions of your microservice interfaces or formal APIs. For example, a service could be a data transformation microservice or a billing API.

    <br><br>

    The main attribute of a service is the destination URL for proxying traffic. This URL can be set as a single string or by specifying its protocol, host, port and path individually.

    <br><br>

    Services are associated to routes, and a single service can have many routes associated with it. Routes are entrypoints in Kong Gateway which define rules to match client requests. Once a route is matched, Kong Gateway proxies the request to its associated service. See the [Route documentation](https://developer.konghq.com/gateway/entities/route/) for a detailed explanation of how Kong proxies traffic.

    <br><br>

    Services can be both [tagged and filtered by tags](https://developer.konghq.com/admin-api/).

    '
  name: Services
paths:
  /{workspace}/services:
    post:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Service#create
      operationId: create-service
      summary: Create a new Service
      description: Create a new Service
      parameters:
      - $ref: '#/components/parameters/Workspace'
      requestBody:
        description: Description of the new Service for creation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '201':
          description: Successfully created Service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Services
  /{workspace}/services/{ServiceIdOrName}:
    parameters:
    - $ref: '#/components/parameters/ServiceIdOrName'
    delete:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Service#delete
      operationId: delete-service
      summary: Delete a Service
      description: Delete a Service
      parameters:
      - $ref: '#/components/parameters/ServiceIdOrName'
      - $ref: '#/components/parameters/Workspace'
      responses:
        '204':
          description: Successfully deleted Service or the resource didn't exist
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Services
    get:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Service#read
      operationId: get-service
      summary: Get a Service
      description: Get a Service using ID or name.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      responses:
        '200':
          description: Successfully fetched Service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/HTTP401Error'
        '404':
          description: Resource does not exist
      tags:
      - Services
    put:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Service#update
      operationId: upsert-service
      summary: Upsert a Service
      description: Create or Update Service using ID or name.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      requestBody:
        description: Description of the Service
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '200':
          description: Successfully upserted Service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Services
  /v2/control-planes/{controlPlaneId}/core-entities/services:
    parameters:
    - $ref: '#/components/parameters/controlPlaneId'
    get:
      operationId: list-service
      summary: List all Services
      description: List all Services
      parameters:
      - $ref: '#/components/parameters/PaginationSize'
      - $ref: '#/components/parameters/PaginationOffset'
      - $ref: '#/components/parameters/PaginationTagsFilter'
      - $ref: '#/components/parameters/NameContainsFilter'
      - $ref: '#/components/parameters/NameEqualsFilter'
      responses:
        '200':
          description: A successful response listing Services
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Service_2'
                  next:
                    $ref: '#/components/schemas/PaginationNextResponse'
                  offset:
                    $ref: '#/components/schemas/PaginationOffsetResponse'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Services
    post:
      operationId: create-service
      summary: Create a new Service
      description: Create a new Service
      requestBody:
        description: Description of the new Service for creation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service_2'
      responses:
        '201':
          description: Successfully created Service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Services
  /v2/control-planes/{controlPlaneId}/core-entities/services/{ServiceId}:
    parameters:
    - $ref: '#/components/parameters/ServiceId'
    - $ref: '#/components/parameters/controlPlaneId'
    delete:
      operationId: delete-service
      summary: Delete a Service
      description: Delete a Service
      parameters:
      - $ref: '#/components/parameters/ServiceId'
      responses:
        '204':
          description: Successfully deleted Service or the resource didn't exist
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Services
    get:
      operationId: get-service
      summary: Get a Service
      description: Get a Service using ID or name.
      responses:
        '200':
          description: Successfully fetched Service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
        '404':
          description: Resource does not exist
      tags:
      - Services
    put:
      operationId: upsert-service
      summary: Upsert a Service
      description: Create or Update Service using ID or name.
      requestBody:
        description: Description of the Service
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service_2'
      responses:
        '200':
          description: Successfully upserted Service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Services
components:
  schemas:
    Service_2:
      description: Service entities, as the name implies, are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc. The main attribute of a Service is its URL (where Kong should proxy traffic to), which can be set as a single string or by specifying its `protocol`, `host`, `port` and `path` individually. Services are associated to Routes (a Service can have many Routes associated with it). Routes are entry-points in Kong and define rules to match client requests. Once a Route is matched, Kong proxies the request to its associated Service. See the [Proxy Reference][proxy-reference] for a detailed explanation of how Kong proxies traffic.
      type: object
      properties:
        ca_certificates:
          description: Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).
          type: array
          items:
            type: string
          nullable: true
        client_certificate:
          description: Certificate to be used as client certificate while TLS handshaking to the upstream server.
          type: object
          nullable: true
          properties:
            id:
              type: string
          x-foreign: true
        connect_timeout:
          description: The timeout in milliseconds for establishing a connection to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          nullable: true
        enabled:
          description: 'Whether the Service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). Default: `true`.'
          type: boolean
          default: true
          nullable: true
        host:
          description: The host of the upstream server. Note that the host value is case sensitive.
          type: string
        id:
          description: A string representing a UUID (universally unique identifier).
          type: string
          minLength: 1
          nullable: true
        name:
          description: The Service name.
          type: string
          nullable: true
        path:
          description: The path to be used in requests to the upstream server.
          type: string
          nullable: true
        port:
          description: The upstream server port.
          type: integer
          default: 80
          maximum: 65535
          minimum: 0
          nullable: true
        protocol:
          description: The protocol used to communicate with the upstream.
          type: string
          default: http
          enum:
          - grpc
          - grpcs
          - http
          - https
          - tcp
          - tls
          - tls_passthrough
          - udp
          - ws
          - wss
          nullable: true
          x-speakeasy-unknown-values: allow
        read_timeout:
          description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
        retries:
          description: The number of retries to execute upon failure to proxy.
          type: integer
          default: 5
          maximum: 32767
          minimum: 0
          nullable: true
        tags:
          description: An optional set of strings associated with the Service for grouping and filtering.
          type: array
          items:
            description: A string representing a tag.
            type: string
          nullable: true
        tls_sans:
          description: Additional Subject Alternative Names that can be matched on Upstream server's TLS certificate (in addition to `host`).
          type: object
          nullable: true
          properties:
            dnsnames:
              description: A dnsName for TLS verification.
              type: array
              items:
                description: A string representing an SNI (server name indication) value for TLS.
                type: string
            uris:
              description: An URI for TLS verification.
              type: array
              items:
                description: A string representing a URL, such as https://example.com/path/to/resource?q=search.
                type: string
        tls_verify:
          description: Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected.
          type: boolean
          nullable: true
        tls_verify_depth:
          description: Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected.
          type: integer
          maximum: 64
          minimum: 0
          nullable: true
        updated_at:
          description: Unix epoch when the resource was last updated.
          type: integer
          nullable: true
        url:
          description: Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses.
          type: string
          writeOnly: true
        write_timeout:
          description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
      example:
        host: example.internal
        id: 49fd316e-c457-481c-9fc7-8079153e4f3c
        name: example-service
        path: /
        port: 80
        protocol: http
      additionalProperties: false
      required:
      - host
    PaginationOffsetResponse:
      description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page
      type: string
    GatewayUnauthorizedError:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
      required:
      - message
      - status
    Service:
      x-speakeasy-entity: Service
      description: Service entities, as the name implies, are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc. The main attribute of a Service is its URL (where Kong should proxy traffic to), which can be set as a single string or by specifying its `protocol`, `host`, `port` and `path` individually. Services are associated to Routes (a Service can have many Routes associated with it). Routes are entry-points in Kong and define rules to match client requests. Once a Route is matched, Kong proxies the request to its associated Service. See the [Proxy Reference][proxy-reference] for a detailed explanation of how Kong proxies traffic.
      type: object
      properties:
        ca_certificates:
          description: Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream server's TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).
          type: array
          items:
            type: string
          nullable: true
        client_certificate:
          description: Certificate to be used as client certificate while TLS handshaking to the upstream server.
          type: object
          nullable: true
          properties:
            id:
              type: string
          x-foreign: true
        connect_timeout:
          description: The timeout in milliseconds for establishing a connection to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          nullable: true
        enabled:
          description: 'Whether the Service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). Default: `true`.'
          type: boolean
          default: true
          nullable: true
        host:
          description: The host of the upstream server. Note that the host value is case sensitive.
          type: string
        id:
          description: A string representing a UUID (universally unique identifier).
          type: string
          minLength: 1
          nullable: true
        name:
          description: The Service name.
          type: string
          nullable: true
        path:
          description: The path to be used in requests to the upstream server.
          type: string
          nullable: true
        port:
          description: The upstream server port.
          type: integer
          default: 80
          maximum: 65535
          minimum: 0
          nullable: true
        protocol:
          description: The protocol used to communicate with the upstream.
          type: string
          default: http
          enum:
          - grpc
          - grpcs
          - http
          - https
          - tcp
          - tls
          - tls_passthrough
          - udp
          - ws
          - wss
          nullable: true
        read_timeout:
          description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
        retries:
          description: The number of retries to execute upon failure to proxy.
          type: integer
          default: 5
          maximum: 32767
          minimum: 0
          nullable: true
        tags:
          description: An optional set of strings associated with the Service for grouping and filtering.
          type: array
          items:
            description: A string representing a tag.
            type: string
          nullable: true
        tls_sans:
          description: Additional Subject Alternative Names that can be matched on Upstream server's TLS certificate (in addition to `host`).
          type: object
          nullable: true
          properties:
            dnsnames:
              description: A dnsName for TLS verification.
              type: array
              items:
                description: A string representing an SNI (server name indication) value for TLS.
                type: string
            uris:
              description: An URI for TLS verification.
              type: array
              items:
                description: A string representing a URL, such as https://example.com/path/to/resource?q=search.
                type: string
        tls_verify:
          description: Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected.
          type: boolean
          nullable: true
        tls_verify_depth:
          description: Maximum depth of chain while verifying Upstream server's TLS certificate. If set to `null`, then the Nginx default is respected.
          type: integer
          maximum: 64
          minimum: 0
          nullable: true
        updated_at:
          description: Unix epoch when the resource was last updated.
          type: integer
          nullable: true
        url:
          description: Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses.
          type: string
          writeOnly: true
        write_timeout:
          description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
      example:
        host: example.internal
        id: 49fd316e-c457-481c-9fc7-8079153e4f3c
        name: example-service
        path: /
        port: 80
        protocol: http
      additionalProperties: false
      required:
      - host
    PaginationNextResponse:
      description: URI to the next page (may be null)
      type: string
  responses:
    HTTP401Error_2:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayUnauthorizedError'
    HTTP401Error:
      description: Unauthorized
      content:
        application/json:
          examples:
            DuplicateApiKey:
              summary: Duplicate API key found
              value:
                message: Duplicate API key found
                status: 401
            InvalidAuthCred:
              summary: Invalid authentication credentials
              value:
                message: Unauthorized
                status: 401
            NoAPIKey:
              summary: No API key found
              value:
                message: No API key found in request
                status: 401
          schema:
            $ref: '#/components/schemas/GatewayUnauthorizedError'
  parameters:
    PaginationSize:
      description: Number of resources to be returned.
      in: query
      name: size
      schema:
        type: integer
        default: 100
        maximum: 1000
        minimum: 1
    ServiceIdOrName:
      description: ID or name of the Service to lookup
      example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
      in: path
      name: ServiceIdOrName
      required: true
      schema:
        type: string
      x-speakeasy-match: id
    Workspace:
      description: The name of the workspace
      in: path
      name: workspace
      required: true
      schema:
        type: string
        example: team-payments
        default: default
    ServiceId:
      description: ID of the Service to lookup
      example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
      in: path
      name: ServiceId
      required: true
      schema:
        type: string
    NameContainsFilter:
      description: Filter routes by a substring of the name.
      example: john
      in: query
      name: filter[name][contains]
      schema:
        type: string
    PaginationOffset:
      allowEmptyValue: true
      description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources
      in: query
      name: offset
      schema:
        type: string
    controlPlaneId:
      name: controlPlaneId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The UUID of your control plane. This variable is available in the Konnect manager.
      x-speakeasy-param-force-new: true
    NameEqualsFilter:
      description: Filter routes by their name.
      example: john
      in: query
      name: filter[name][eq]
      schema:
        type: string
    PaginationTagsFilter:
      allowEmptyValue: true
      description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using ',' to mean AND or using '/' to mean OR.
      example: tag1,tag2
      in: query
      name: tags
      schema:
        type: string
  securitySchemes:
    adminToken:
      in: header
      name: Kong-Admin-Token
      type: apiKey
externalDocs:
  description: Documentation for Kong Gateway and its APIs
  url: https://developer.konghq.com