Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.

Kong Admin API

Kong comes with an internal RESTful Admin API for administration purposes. Requests to the Admin API can be sent to any node in the cluster, and Kong will keep the configuration consistent across all nodes.

  • 8001 is the default port on which the Admin API listens.
  • 8444 is the default port for HTTPS traffic to the Admin API.

This API is designed for internal use and provides full control over Kong, so care should be taken when setting up Kong environments to avoid undue public exposure of this API. See this document for a discussion of methods to secure the Admin API.

Supported Content Types

The Admin API accepts 2 content types on every endpoint:

  • application/x-www-form-urlencoded

Simple enough for basic request bodies, you will probably use it most of the time. Note that when sending nested values, Kong expects nested objects to be referenced with dotted keys. Example:

config.limit=10&config.period=seconds
  • application/json

Handy for complex bodies (ex: complex plugin configuration), in that case simply send a JSON representation of the data you want to send. Example:

{
    "config": {
        "limit": 10,
        "period": "seconds"
    }
}

Information routes

Retrieve node information

Retrieve generic details about a node.

Endpoint

/

Response

HTTP 200 OK
{
    "hostname": "",
    "lua_version": "LuaJIT 2.1.0-alpha",
    "plugins": {
        "available_on_server": [
            ...
        ],
        "enabled_in_cluster": [
            ...
        ]
    },
    "configuration" : {
        ...
    },
    "tagline": "Welcome to Kong",
    "version": "0.10.0"
}
  • available_on_server: Names of plugins that are installed on the node.
  • enabled_in_cluster: Names of plugins that are enabled/configured. That is, the plugins configurations currently in the datastore shared by all Kong nodes.

Retrieve node status

Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, and the number of entities stored in the datastore collections (including plugin's collections).

If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used.

Endpoint

/status

Response

HTTP 200 OK
{
    "server": {
        "total_requests": 3,
        "connections_active": 1,
        "connections_accepted": 1,
        "connections_handled": 1,
        "connections_reading": 0,
        "connections_writing": 1,
        "connections_waiting": 0
    },
    "database": {
        "apis": 2,
        "consumers": 0,
        "plugins": 2,
        "nodes": 1,
        ...
    }
}
  • server: Metrics about the nginx HTTP/S server.
    • total_requests: The total number of client requests.
    • connections_active: The current number of active client connections including Waiting connections.
    • connections_accepted: The total number of accepted client connections.
    • connections_handled: The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.
    • connections_reading: The current number of connections where Kong is reading the request header.
    • connections_writing: The current number of connections where nginx is writing the response back to the client.
    • connections_waiting: The current number of idle client connections waiting for a request.
  • database: Metrics about the database collections.
    • ...: For every database collection, shows the number of items stored in that collection.

Cluster

You can see the Kong cluster members, add a node to the cluster and forcibly remove a node from the cluster, using the following endpoints. For more information read the clustering documentation. You can also execute some of these operations using the CLI.


Retrieve cluster status

Retrieve the cluster status, returning information for each node in the cluster.

Endpoint

/cluster

Response

HTTP 200 OK
{
    "data": [
        {
            "address": "172.30.0.4:7946",
            "name": "3f86eadb04c9_0.0.0.0:7946_b1dae503e0f34f9c9bf9be0a5023461d",
            "status": "alive"
        },
        {
            "address": "172.30.0.5:7946",
            "name": "3b42de4b1a43_0.0.0.0:7946_5b0f4afcfe4e45c6b5d40cef6a256311",
            "status": "alive"
        }
    ],
    "total": 2
}

Add a node

Add a node to the cluster.

Endpoint

/cluster

Request Body

Attributes Description
address The node address to add.

Response

HTTP 200 OK

Forcibly remove a node

Forcibly remove a node from the cluster.

Endpoint

/cluster

Request Body

Attributes Description
name The node name to remove.

Response

HTTP 200 OK

API Object

The API object describes an API that's being exposed by Kong. Kong needs to know how to retrieve the API when a consumer is calling it from the Proxy port. Each API object must specify some combination of hosts, uris, and methods. Kong will proxy all requests to the API to the specified upstream URL.

{
    "created_at": 1488830759000,
    "hosts": [
        "example.org"
    ],
    "http_if_terminated": true,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "example-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

Add API

Endpoint

/apis/

Request Body

Attribute Description
name The API name.
hosts
semi-optional
A comma-separated list of domain names that point to your API. For example: example.com. At least one of hosts, uris, or methods should be specified.
uris
semi-optional
A comma-separated list of URIs prefixes that point to your API. For example: /my-path. At least one of hosts, uris, or methods should be specified.
methods
semi-optional
A comma-separated list of HTTP methods that point to your API. For example: GET,POST. At least one of hosts, uris, or methods should be specified.
upstream_url The base target URL that points to your API server. This URL will be used for proxying requests. For example: https://example.com.
strip_uri
optional
When matching an API via one of the uris prefixes, strip that matching prefix from the upstream URI to be requested. Default: true.
preserve_host
optional
When matching an API via one of the hosts domain names, make sure the request Host header is forwarded to the upstream service. By default, this is false, and the upstream Host header will be extracted from the configured upstream_url.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
upstream_connect_timeout
optional
The timeout in milliseconds for establishing a connection to your upstream service. Defaults to 60000.
upstream_send_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to your upstream service Defaults to 60000.
upstream_read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to your upstream service Defaults to 60000.
https_only
optional
To be enabled if you wish to only serve an API through HTTPS, on the appropriate port (8443 by default). Default: false.
http_if_terminated
optional
Consider the X-Forwarded-Proto header when enforcing HTTPS only traffic. Default: true.

Response

HTTP 201 Created
{
    "created_at": 1488830759000,
    "hosts": [
        "example.org"
    ],
    "http_if_terminated": true,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "example-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

Retrieve API

Endpoint

/apis/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the API to retrieve

Response

HTTP 200 OK
{
    "created_at": 1488830759000,
    "hosts": [
        "example.org"
    ],
    "http_if_terminated": true,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "example-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

List APIs

Endpoint

/apis/

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the apis id field.
name
optional
A filter on the list based on the apis name field.
upstream_url
optional
A filter on the list based on the apis upstream_url field.
retries
optional
A filter on the list based on the apis retries field.
size
optional, default is 100
A limit on the number of objects to be returned.
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.

Response

HTTP 200 OK
{
    "total": 10,
    "data": [
        {
            "created_at": 1488830759000,
            "hosts": [
                "example.org"
            ],
            "http_if_terminated": true,
            "https_only": false,
            "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
            "name": "example-api",
            "preserve_host": false,
            "retries": 5,
            "strip_uri": true,
            "upstream_connect_timeout": 60000,
            "upstream_read_timeout": 60000,
            "upstream_send_timeout": 60000,
            "upstream_url": "http://httpbin.org"
        },
        {
            "created_at": 1488830708000,
            "hosts": [
                "api.com"
            ],
            "http_if_terminated": true,
            "https_only": false,
            "id": "0924978e-eb19-44a0-9adc-55f20db2f04d",
            "name": "my-api",
            "preserve_host": false,
            "retries": 10,
            "strip_uri": true,
            "upstream_connect_timeout": 1000,
            "upstream_read_timeout": 1000,
            "upstream_send_timeout": 1000,
            "upstream_url": "http://my-api.com"
        }
    ],
    "next": "http://localhost:8001/apis?size=2&offset=6378122c-a0a1-438d-a5c6-efabae9fb969"
}

Update API

Endpoint

/apis/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the API to update

Request Body

Attribute Description
name The API name.
hosts
semi-optional
A comma-separated list of domain names that point to your API. For example: example.com. At least one of hosts, uris, or methods should be specified.
uris
semi-optional
A comma-separated list of URIs prefixes that point to your API. For example: /my-path. At least one of hosts, uris, or methods should be specified.
methods
semi-optional
A comma-separated list of HTTP methods that point to your API. For example: GET,POST. At least one of hosts, uris, or methods should be specified.
upstream_url The base target URL that points to your API server. This URL will be used for proxying requests. For example: https://example.com.
strip_uri
optional
When matching an API via one of the uris prefixes, strip that matching prefix from the upstream URI to be requested. Default: true.
preserve_host
optional
When matching an API via one of the hosts domain names, make sure the request Host header is forwarded to the upstream service. By default, this is false, and the upstream Host header will be extracted from the configured upstream_url.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
upstream_connect_timeout
optional
The timeout in milliseconds for establishing a connection to your upstream service. Defaults to 60000.
upstream_send_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to your upstream service Defaults to 60000.
upstream_read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to your upstream service Defaults to 60000.
https_only
optional
To be enabled if you wish to only serve an API through HTTPS, on the appropriate port (8443 by default). Default: false.
http_if_terminated
optional
Consider the X-Forwarded-Proto header when enforcing HTTPS only traffic. Default: true.

Response

HTTP 200 OK
{
    "created_at": 1488830759000,
    "hosts": [
        "updated-example.org"
    ],
    "http_if_terminated": true,
    "https_only": false,
    "id": "6378122c-a0a1-438d-a5c6-efabae9fb969",
    "name": "my-updated-api",
    "preserve_host": false,
    "retries": 5,
    "strip_uri": true,
    "upstream_connect_timeout": 60000,
    "upstream_read_timeout": 60000,
    "upstream_send_timeout": 60000,
    "upstream_url": "http://httpbin.org"
}

Update Or Create API

Endpoint

/apis/

Request Body

Attribute Description
name The API name.
hosts
semi-optional
A comma-separated list of domain names that point to your API. For example: example.com. At least one of hosts, uris, or methods should be specified.
uris
semi-optional
A comma-separated list of URIs prefixes that point to your API. For example: /my-path. At least one of hosts, uris, or methods should be specified.
methods
semi-optional
A comma-separated list of HTTP methods that point to your API. For example: GET,POST. At least one of hosts, uris, or methods should be specified.
upstream_url The base target URL that points to your API server. This URL will be used for proxying requests. For example: https://example.com.
strip_uri
optional
When matching an API via one of the uris prefixes, strip that matching prefix from the upstream URI to be requested. Default: true.
preserve_host
optional
When matching an API via one of the hosts domain names, make sure the request Host header is forwarded to the upstream service. By default, this is false, and the upstream Host header will be extracted from the configured upstream_url.
retries
optional
The number of retries to execute upon failure to proxy. The default is 5.
upstream_connect_timeout
optional
The timeout in milliseconds for establishing a connection to your upstream service. Defaults to 60000.
upstream_send_timeout
optional
The timeout in milliseconds between two successive write operations for transmitting a request to your upstream service Defaults to 60000.
upstream_read_timeout
optional
The timeout in milliseconds between two successive read operations for transmitting a request to your upstream service Defaults to 60000.
https_only
optional
To be enabled if you wish to only serve an API through HTTPS, on the appropriate port (8443 by default). Default: false.
http_if_terminated
optional
Consider the X-Forwarded-Proto header when enforcing HTTPS only traffic. Default: true.

The body needs an id parameter to trigger an update on an existing entity.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete API

Endpoint

/apis/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the API to delete

Response

HTTP 204 No Content

Consumer Object

The Consumer object represents a consumer - or a user - of an API. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.

{
    "custom_id": "abc123"
}

Create Consumer

Endpoint

/consumers/

Request Form Parameters

Attributes Description
username
semi-optional
The unique username of the consumer. You must send either this field or custom_id with the request.
custom_id
semi-optional
Field for storing an existing unique ID for the consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

Response

HTTP 201 Created
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "custom_id": "abc123",
    "created_at": 1422386534
}

Retrieve Consumer

Endpoint

/consumers/{username or id}
Attributes Description
username or id
required
The unique identifier or the username of the consumer to retrieve

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "custom_id": "abc123",
    "created_at": 1422386534
}

List Consumers

Endpoint

/consumers/

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the consumer id field.
custom_id
optional
A filter on the list based on the consumer custom_id field.
username
optional
A filter on the list based on the consumer username field.
size
optional, default is 100
A limit on the number of objects to be returned.
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.

Response

HTTP 200 OK
{
    "total": 10,
    "data": [
        {
            "id": "4d924084-1adb-40a5-c042-63b19db421d1",
            "custom_id": "abc123",
            "created_at": 1422386534
        },
        {
            "id": "3f924084-1adb-40a5-c042-63b19db421a2",
            "custom_id": "def345",
            "created_at": 1422386585
        }
    ],
    "next": "http://localhost:8001/consumers/?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

Update Consumer

Endpoint

/consumers/{username or id}
Attributes Description
username or id
required
The unique identifier or the username of the consumer to update

Request Body

Attributes Description
username
semi-optional
The unique username of the consumer. You must send either this field or custom_id with the request.
custom_id
semi-optional
Field for storing an existing unique ID for the consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "custom_id": "updated_abc123",
    "created_at": 1422386534
}

Update Or Create Consumer

Endpoint

/consumers/

Request Body

Attributes Description
username
semi-optional
The unique username of the consumer. You must send either this field or custom_id with the request.
custom_id
semi-optional
Field for storing an existing unique ID for the consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request.

The body needs an id parameter to trigger an update on an existing entity.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete Consumer

Endpoint

/consumers/{username or id}
Attributes Description
username or id
required
The unique identifier or the name of the consumer to delete

Response

HTTP 204 No Content

Plugin Object

A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response workflow, and it's how you can add functionalities to APIs that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the Plugin Gallery.

When creating adding Plugin on top of an API, every request made by a client will be evaluated by the Plugin's configuration you setup. Sometimes the Plugin needs to be tuned to different values for some specific consumers, you can do that by specifying the consumer_id value.

{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

Add Plugin

You can add a plugin in four different ways:

  • For every API and Consumer. Don't set api_id and consumer_id.
  • For every API and a specific Consumer. Only set consumer_id.
  • For every Consumer and a specific API. Only set api_id.
  • For a specific Consumer and API. Set both api_id and consumer_id.

Note that not all plugins allow to specify consumer_id. Check the plugin documentation.

Endpoint

/apis/{name or id}/plugins/
Attributes Description
name or id
required
The unique identifier or the name of the API on which to add a plugin configuration. If you are adding a plugin to every API use the /plugins endpoint instead without specifying an api_id.

Request Body

Attributes Description
name The name of the Plugin that's going to be added. Currently the Plugin must be installed in every Kong instance separately.
consumer_id
optional
The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests.
config.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.

Response

HTTP 201 Created
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

Retrieve Plugin

/plugins/{id}

Request Querystring Parameters

Attributes Description
id
required
The unique identifier of the plugin to retrieve

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

List All Plugins

Endpoint

/plugins/

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the id field.
name
optional
A filter on the list based on the name field.
api_id
optional
A filter on the list based on the api_id field.
consumer_id
optional
A filter on the list based on the consumer_id field.
size
optional, default is 100
A limit on the number of objects to be returned.
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.

Response

HTTP 200 OK
{
    "total": 10,
    "data": [
      {
          "id": "4d924084-1adb-40a5-c042-63b19db421d1",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "name": "rate-limiting",
          "config": {
              "minute": 20,
              "hour": 500
          },
          "enabled": true,
          "created_at": 1422386534
      },
      {
          "id": "3f924084-1adb-40a5-c042-63b19db421a2",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
          "name": "rate-limiting",
          "config": {
              "minute": 300,
              "hour": 20000
          },
          "enabled": true,
          "created_at": 1422386585
      }
    ],
    "next": "http://localhost:8001/plugins?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

List Plugins per API

Endpoint

/apis/{api name or id}/plugins/

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the id field.
name
optional
A filter on the list based on the name field.
api_id
optional
A filter on the list based on the api_id field.
consumer_id
optional
A filter on the list based on the consumer_id field.
size
optional, default is 100
A limit on the number of objects to be returned.
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.

Response

HTTP 200 OK
{
    "total": 10,
    "data": [
      {
          "id": "4d924084-1adb-40a5-c042-63b19db421d1",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "name": "rate-limiting",
          "config": {
              "minute": 20,
              "hour": 500
          },
          "enabled": true,
          "created_at": 1422386534
      },
      {
          "id": "3f924084-1adb-40a5-c042-63b19db421a2",
          "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
          "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
          "name": "rate-limiting",
          "config": {
              "minute": 300,
              "hour": 20000
          },
          "enabled": true,
          "created_at": 1422386585
      }
    ],
    "next": "http://localhost:8001/plugins?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

Update Plugin

Endpoint

/apis/{api name or id}/plugins/{plugin name or id}
Attributes Description
api name or id
required
The unique identifier or the name of the API for which to update the plugin configuration
plugin name or id
required
The unique identifier or the name of the plugin configuration to update on this API

Request Body

Attributes Description
name The name of the Plugin that's going to be added. Currently the Plugin must be installed in every Kong instance separately.
consumer_id
optional
The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests.
config.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "api_id": "5fd1z584-1adb-40a5-c042-63b19db49x21",
    "consumer_id": "a3dX2dh2-1adb-40a5-c042-63b19dbx83hF4",
    "name": "rate-limiting",
    "config": {
        "minute": 20,
        "hour": 500
    },
    "enabled": true,
    "created_at": 1422386534
}

Update or Add Plugin

Endpoint

/apis/{api name or id}/plugins/
Attributes Description
api name or id
required
The unique identifier or the name of the API for which to update or create the plugin configuration

Request Body

Attributes Description
name The name of the Plugin that's going to be added. Currently the Plugin must be installed in every Kong instance separately.
consumer_id
optional
The unique identifier of the consumer that overrides the existing settings for this specific consumer on incoming requests.
config.{property} The configuration properties for the Plugin which can be found on the plugins documentation page in the Plugin Gallery.

The body needs an id parameter to trigger an update on an existing entity.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete Plugin

Endpoint

/apis/{api name or id}/plugins/{plugin name or id}
Attributes Description
api name or id
required
The unique identifier or the name of the API for which to delete the plugin configuration
plugin name or id
required
The unique identifier or the name of the plugin configuration to delete on this API

Response

HTTP 204 No Content

Retrieve Enabled Plugins

Retrieve a list of all installed plugins on the Kong node.

Endpoint

/plugins/enabled

Response

HTTP 200 OK
{
    "enabled_plugins": [
        "jwt",
        "acl",
        "cors",
        "oauth2",
        "tcp-log",
        "udp-log",
        "file-log",
        "http-log",
        "key-auth",
        "hmac-auth",
        "basic-auth",
        "ip-restriction",
        "request-transformer",
        "response-transformer",
        "request-size-limiting",
        "rate-limiting",
        "response-ratelimiting",
        "aws-lambda",
        "bot-detection",
        "correlation-id",
        "datadog",
        "galileo",
        "ldap-auth",
        "loggly",
        "runscope",
        "statsd",
        "syslog"
    ]
}

Retrieve Plugin Schema

Retrieve the schema of a plugin's configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong's plugin system.

/plugins/schema/{plugin name}

Response

HTTP 200 OK
{
    "fields": {
        "hide_credentials": {
            "default": false,
            "type": "boolean"
        },
        "key_names": {
            "default": "function",
            "required": true,
            "type": "array"
        }
    }
}

Certificate Object

A certificate object represents a public certificate/private key pair for an SSL certificate. These objects are used by Kong to handle SSL/TLS termination for encrypted requests. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames.

{
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----..."
}

Add Certificate

Endpoint

/certificates/

Request Body

Attributes Description
cert PEM-encoded public certificate of the SSL key pair.
key PEM-encoded private key of the SSL key pair.
snis
optional
One or more hostnames to associate with this certificate as an SNI. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience.

Response

HTTP 201 Created
{
    "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "snis": [
        "example.com"
    ],
    "created_at": 1485521710265
}

Retrieve Certificate

Endpoint

/certificates/{sni or id}
Attributes Description
SNI or id
required
The unique identifier or an SNI name associated with this certificate.

Response

HTTP 200 OK
{
    "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "snis": [
        "example.com"
    ],
    "created_at": 1485521710265
}

List Certificates

Endpoint

/certificates/

Response

HTTP 200 OK
{
    "total": 2,
    "data": [
        {
            "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
            "cert": "-----BEGIN CERTIFICATE-----...",
            "key": "-----BEGIN RSA PRIVATE KEY-----...",
            "snis": [
                "example.com"
            ],
            "created_at": 1485521710265
        },
        {
            "id": "6b5b6f71-c0b3-426d-8f3b-8de2c67c816b",
            "cert": "-----BEGIN CERTIFICATE-----...",
            "key": "-----BEGIN RSA PRIVATE KEY-----...",
            "snis": [
                "example.org"
            ],
            "created_at": 1485522651185
        }
    ]
}

Update Certificate

/certificates/{sni or id}
Attributes Description
SNI or id
required
The unique identifier or an SNI name associated with this certificate.

Request Body

Attributes Description
cert PEM-encoded public certificate of the SSL key pair.
key PEM-encoded private key of the SSL key pair.
snis
optional
One or more hostnames to associate with this certificate as an SNI. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience.

Response

HTTP 200 OK
{
    "id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----...",
    "snis": [
        "example.com"
    ],
    "created_at": 1485521710265
}

Update or Create Certificate

Endpoint

/certificates/

Request Body

Attributes Description
cert PEM-encoded public certificate of the SSL key pair.
key PEM-encoded private key of the SSL key pair.
snis
optional
One or more hostnames to associate with this certificate as an SNI. This is a sugar parameter that will, under the hood, create an SNI object and associate it with this certificate for your convenience.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete Certificate

/certificates/{sni or id}
Attributes Description
sni or id
required
The unique identifier or an SNI name associated with this certificate.

Response

HTTP 204 No Content

SNI Objects

An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate.

{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68"
}

Add SNI

Endpoint

/snis/

Request Body

Attributes Description
name The SNI name to associate with the given certificate.
ssl_certificate_id The id (a UUID) of the certificate with which to associate the SNI hostname.

Response

HTTP 201 Created
{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "created_at": 1485521710265
}

Retrieve SNI

Endpoint

/snis/{name}
Attributes Description
name
required
The name of the SNI object.

Response

HTTP 200 OK
{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "created_at": 1485521710265
}

List SNIs

Endpoint

/snis/

Response

HTTP 200 OK
{
    "total": 2,
    "data": [
        {
            "name": "example.com",
            "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
            "created_at": 1485521710265
        },
        {
            "name": "example.org",
            "ssl_certificate_id": "6b5b6f71-c0b3-426d-8f3b-8de2c67c816b",
            "created_at": 1485521710265
        }
    ]
}

Update SNI

/snis/{name}
Attributes Description
name
required
The name of the SNI object.

Response

HTTP 200 OK
{
    "name": "example.com",
    "ssl_certificate_id": "21b69eab-09d9-40f9-a55e-c4ee47fada68",
    "created_at": 1485521710265
}

Update or Create SNI

Endpoint

/snis/

Request Body

Attributes Description
name The SNI name to associate with the given certificate.
ssl_certificate_id The id (a UUID) of the certificate with which to associate the SNI hostname.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete SNI

/snis/{name}
Attributes Description
name
required
The name of the SNI object.

Response

HTTP 204 No Content

Upstream Objects

The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named service.v1.xyz with an API object created with an upstream_url=https://service.v1.xyz/some/path. Requests for this API would be proxied to the targets defined within the upstream.

{
    "name": "service.v1.xyz",
    "orderlist": [
        1,
        2,
        7,
        9,
        6,
        4,
        5,
        10,
        3,
        8
    ],
    "slots": 10
}

Add upstream

Endpoint

/upstreams/

Request Body

Attributes Description
name This is a hostname like name that can be referenced in an upstream_url field of an api.
slots
optional
The number of slots in the loadbalancer algorithm (10-65536, defaults to 1000).
orderlist
optional
A list of sequential, but randomly ordered, integer numbers that determine the distribution of the slots in the balancer. If omitted it will be generated. If given, it must have exactly slots number of entries.

Response

HTTP 201 Created
{
    "id": "13611da7-703f-44f8-b790-fc1e7bf51b3e",
    "name": "service.v1.xyz",
    "orderlist": [
        1,
        2,
        7,
        9,
        6,
        4,
        5,
        10,
        3,
        8
    ],
    "slots": 10,
    "created_at": 1485521710265
}

Retrieve upstream

Endpoint

/upstreams/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the upstream to retrieve

Response

HTTP 200 OK
{
    "id": "13611da7-703f-44f8-b790-fc1e7bf51b3e",
    "name": "service.v1.xyz",
    "orderlist": [
        1,
        2,
        7,
        9,
        6,
        4,
        5,
        10,
        3,
        8
    ],
    "slots": 10,
    "created_at": 1485521710265
}

List upstreams

Endpoint

/upstreams/

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the upstream id field.
name
optional
A filter on the list based on the upstream name field.
slots
optional
A filter on the list based on the upstream slots field.
size
optional, default is 100
A limit on the number of objects to be returned.
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.

Response

HTTP 200 OK
{
    "total": 3,
    "data": [
        {
            "created_at": 1485521710265,
            "id": "13611da7-703f-44f8-b790-fc1e7bf51b3e",
            "name": "service.v1.xyz",
            "orderlist": [
                1,
                2,
                7,
                9,
                6,
                4,
                5,
                10,
                3,
                8
            ],
            "slots": 10
        },
        {
            "created_at": 1485522651185,
            "id": "07131005-ba30-4204-a29f-0927d53257b4",
            "name": "service.v2.xyz",
            "orderlist": [
                5,
                3,
                6,
                1,
                2,
                10,
                8,
                7,
                4,
                9
            ],
            "slots": 10
        }
    ],
    "next": "http://localhost:8001/upstreams?size=2&offset=Mg%3D%3D",
    "offset": "Mg=="
}

Update upstream

Endpoint

/upstreams/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the upstream to update

Request Body

Attributes Description
name This is a hostname like name that can be referenced in an upstream_url field of an api.
slots
optional
The number of slots in the loadbalancer algorithm (10-65536, defaults to 1000).
orderlist
optional
A list of sequential, but randomly ordered, integer numbers that determine the distribution of the slots in the balancer. If omitted it will be generated. If given, it must have exactly slots number of entries.

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "service.v1.xyz",
    "orderlist": [
        1,
        2,
        7,
        9,
        6,
        4,
        5,
        10,
        3,
        8
    ],
    "slots": 10,
    "created_at": 1422386534
}

Update Or create Upstream

Endpoint

/upstreams/

Request Body

Attributes Description
name This is a hostname like name that can be referenced in an upstream_url field of an api.
slots
optional
The number of slots in the loadbalancer algorithm (10-65536, defaults to 1000).
orderlist
optional
A list of sequential, but randomly ordered, integer numbers that determine the distribution of the slots in the balancer. If omitted it will be generated. If given, it must have exactly slots number of entries.

The body needs an id parameter to trigger an update on an existing entity.

Response

HTTP 201 Created or HTTP 200 OK

See POST and PATCH responses.


Delete upstream

Endpoint

/upstreams/{name or id}
Attributes Description
name or id
required
The unique identifier or the name of the upstream to delete

Response

HTTP 204 No Content

Target Object

A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added. Changes are effectuated on the fly.

Because the upstream maintains a history of target changes, the targets cannot be deleted or modified. To disable a target, post a new one with weight=0; alternatively, use the DELETE convenience method to accomplish the same.

The current target object definition is the one with the latest created_at.

{
    "target": "1.2.3.4:80",
    "weight": 15,
    "upstream_id": "ee3310c1-6789-40ac-9386-f79c0cb58432"
}

Add target

Endpoint

/upstreams/{name or id}/targets
Attributes Description
name or id
required
The unique identifier or the name of the upstream to which to add the target

Request Body

Attributes Description
target The target address (ip or hostname) and port. If omitted the port defaults to 8000. If the hostname resolves to an SRV record, the port value will overridden by the value from the dns record.
weight
optional
The weight this target gets within the upstream loadbalancer (0-1000, defaults to 100). If the hostname resolves to an SRV record, the weight value will overridden by the value from the dns record.

Response

HTTP 201 Created
{
    "id": "4661f55e-95c2-4011-8fd6-c5c56df1c9db",
    "target": "1.2.3.4:80",
    "weight": 15,
    "upstream_id": "ee3310c1-6789-40ac-9386-f79c0cb58432",
    "created_at": 1485523507446
}

List targets

Lists all targets of the upstream. Multiple target objects for the same target may be returned, showing the history of changes for a specific target. The target object with the latest created_at is the current definition.

Endpoint

/upstreams/{name or id}/targets
Attributes Description
name or id
required
The unique identifier or the name of the upstream for which to list the targets

Request Querystring Parameters

Attributes Description
id
optional
A filter on the list based on the target id field.
target
optional
A filter on the list based on the target target field.
weight
optional
A filter on the list based on the target weight field.
size
optional, default is 100
A limit on the number of objects to be returned.
offset
optional
A cursor used for pagination. offset is an object identifier that defines a place in the list.

Response

HTTP 200 OK
{
    "total": 30,
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524897232,
            "id": "9b96f13d-65af-4f30-bbe9-b367121dd26b",
            "target": "127.0.0.1:20001",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 0
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }
    ]
}

List active targets

Retrieve a list of active targets (targets whose most recent weight is not 0) for a given upstream.

Note: This endpoint is only available with Kong 0.10.1+

Endpoint

/upstreams/{name or id}/targets/active
Attributes Description
name or id
required
The unique identifier or the name of the upstream for which to list the targets.

Response

HTTP 200 OK
{
    "total": 2,
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }
    ]
}

Delete target

Disable a target in the load balancer. Under the hood, this method creates a new entry for the given target definition with a weight of 0.

Note: This endpoint is only available with Kong 0.10.1+

Endpoint

/upstreams/{upstream name or id}/targets/{target or id}
Attributes Description
upstream name or id
required
The unique identifier or the name of the upstream for which to delete the target.
target or id
required
The host/port combination element of the target to remove, or the id of an existing target entry.

Response

HTTP 204 No Content

Keep up with the latest features