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 API for administration purposes. API commands can be run on any node in the cluster, and Kong will keep the configuration consistent across all nodes.

  • The RESTful Admin API listens on port 8001 by default.

Supported Content Types

The Admin API accepts 2 content types on every endpoint:

  • 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 representaton 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.6.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, and forcibly remove a node from the cluster, using the following endpoints. For more information read the clustering documentation. You can also execute 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
{
    "total": 3,
    "data": [
        {
            "address": "192.168.1.107:7946",
            "name": "kong.prod1_7946",
            "status": "alive"
        },
        {
            "address": "192.168.2.127:7946",
            "name": "kong.prod2_7946",
            "status": "failed"
        },
        {
            "address": "192.168.3.112:8484",
            "name": "kong.prod3_8484",
            "status": "left"
        }
    ]
}

Forcibly remove a node

Forcibly remove a node from the cluster.

Endpoint

/cluster

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 a request host, a request path or both. Kong will proxy all requests to the API to the specified upstream URL.

{
    "name": "Mockbin",
    "request_host": "mockbin.com",
    "request_path": "/someservice",
    "strip_request_path": false,
    "preserve_host": false,
    "upstream_url": "https://mockbin.com"
}

Add API

Endpoint

/apis/

Request Body

Attribute Description
name
optional
The API name. If none is specified, will default to the request_host or request_path.
request_host
semi-optional
The public DNS address that points to your API. For example, mockbin.com. At least request_host or request_path or both should be specified.
request_path
semi-optional
The public path that points to your API. For example, /someservice. At least request_host or request_path or both should be specified.
strip_request_path
optional
Strip the request_path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to upstream_url/hello. By default is false.
preserve_host
optional
Preserves the original Host header sent by the client, instead of replacing it with the hostname of the upstream_url. By default is false.
upstream_url The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com.

Response

HTTP 201 Created
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "Mockbin",
    "request_host": "mockbin.com",
    "upstream_url": "http://mockbin.com",
    "preserve_host": false,
    "created_at": 1422386534
}

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
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "Mockbin",
    "request_host": "mockbin.com",
    "upstream_url": "https://mockbin.com",
    "preserve_host": false,
    "created_at": 1422386534
}

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.
request_host
optional
A filter on the list based on the apis request_host field.
request_path
optional
A filter on the list based on the apis request_path field.
upstream_url
optional
A filter on the list based on the apis upstream_url 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",
            "name": "Mockbin",
            "request_host": "mockbin.com",
            "upstream_url": "https://mockbin.com",
            "preserve_host": false,
            "created_at": 1422386534
        },
        {
            "id": "3f924084-1adb-40a5-c042-63b19db421a2",
            "name": "PrivateAPI",
            "request_host": "internal.api.com",
            "upstream_url": "http://private.api.com",
            "preserve_host": false,
            "created_at": 1422386585
        }
    ],
    "next": "http://localhost:8001/apis/?size=2&offset=4d924084-1adb-40a5-c042-63b19db421d1"
}

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
optional
The API name. If none is specified, will default to the request_host or request_path.
request_host
semi-optional
The public DNS address that points to your API. For example, mockbin.com. At least request_host or request_path or both should be specified.
request_path
semi-optional
The public path that points to your API. For example, /someservice. At least request_host or request_path or both should be specified.
strip_request_path
optional
Strip the request_path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to upstream_url/hello. By default is false.
preserve_host
optional
Preserves the original Host header sent by the client, instead of replacing it with the hostname of the upstream_url. By default is false.
upstream_url The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com.

Response

HTTP 200 OK
{
    "id": "4d924084-1adb-40a5-c042-63b19db421d1",
    "name": "Mockbin2",
    "request_host": "mockbin.com",
    "upstream_url": "http://mockbin.com",
    "preserve_host": false,
    "created_at": 1422386534
}

Update Or Create API

Endpoint

/apis/

Request Body

Attribute Description
name
optional
The API name. If none is specified, will default to the request_host or request_path.
request_host
semi-optional
The public DNS address that points to your API. For example, mockbin.com. At least request_host or request_path or both should be specified.
request_path
semi-optional
The public path that points to your API. For example, /someservice. At least request_host or request_path or both should be specified.
strip_request_path
optional
Strip the request_path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to upstream_url/hello. By default is false.
preserve_host
optional
Preserves the original Host header sent by the client, instead of replacing it with the hostname of the upstream_url. By default is false.
upstream_url The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com.

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 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 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 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 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 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 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

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

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/{id}
Attributes Description
api name or id
required
The unique identifier or the name of the API for which to update the plugin configuration
id
required
The unique identifier 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/{id}
Attributes Description
api name or id
required
The unique identifier or the name of the API for which to delete the plugin configuration
id
required
The unique identifier 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": [
        "ssl",
        "jwt",
        "acl",
        "cors",
        "oauth2",
        "tcp-log",
        "udp-log",
        "file-log",
        "http-log",
        "key-auth",
        "hmac-auth",
        "basic-auth",
        "ip-restriction",
        "mashape-analytics",
        "request-transformer",
        "response-transformer",
        "request-size-limiting",
        "rate-limiting",
        "response-ratelimiting"
    ]
}

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"
        }
    }
}