You are browsing unreleased documentation. See the latest documentation here.

Kong Gateway Admin API

Kong Gateway 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 Securing the Admin API for more information about security methods.

Documentation

The Kong Admin API is documented in OpenAPI format:

Spec	Insomnia link
Enterprise API
Open source API

See the following links for individual entity documentation:

DB-less mode

In DB-less mode, you configure Kong Gateway declaratively. The Admin API for each Kong node functions independently, reflecting the memory state of that particular Kong node. This is the case because there is no database coordination between Kong nodes. Therefore, the Admin API is mostly read-only.

When running Kong Gateway in DB-less mode, the Admin API can only perform tasks related to handling the declarative config:

• Validating configurations against schemas
• Validating plugin configurations against schemas
• Reloading the declarative configuration

Supported content types

The Admin API accepts 3 content types on every endpoint:

application/json

The application/json content type is useful for complex bodies (for example, complex plugin configuration). Send a JSON representation of the data you want to send. For example:

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

Here’s an example of adding a route to a service named test-service:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -H "Content-Type: application/json" \
     -d '{"name": "test-route", "paths": [ "/path/one", "/path/two" ]}'

application/x-www-form-urlencoded

The content type application/x-www-form-urlencoded is useful for basic request bodies. You can use it in most situations. Note that when sending nested values, Kong expects nested objects to be referenced with dotted keys. Example:

config.limit=10&config.period=seconds

When specifying arrays, send the values in order, or use square brackets (numbering inside the brackets is optional but if provided it must be 1-indexed, and consecutive).

Here’s an example route added to a service named test-service:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -d "name=test-route" \
     -d "paths[1]=/path/one" \
     -d "paths[2]=/path/two"

The following two examples are identical to the one above, but less explicit:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -d "name=test-route" \
     -d "paths[]=/path/one" \
     -d "paths[]=/path/two"

curl -i -X POST http://localhost:8001/services/test-service/routes \
    -d "name=test-route" \
    -d "paths=/path/one" \
    -d "paths=/path/two"

multipart/form-data

The multipart/form-data content type is similar to URL-encoded. This content type uses dotted keys to reference nested objects. Here is an example of sending a Lua file to the pre-function Kong plugin:

curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \
     -F "name=pre-function" \
     -F "config.access=@custom-auth.lua"

When specifying arrays for this content-type, the array indices must be specified. For example, here’s a route added to a service named test-service:

curl -i -X POST http://localhost:8001/services/test-service/routes \
     -F "name=test-route" \
     -F "paths[1]=/path/one" \
     -F "paths[2]=/path/two"

HTTP status response codes

The following status codes are returned in HTTP responses:

Using the API in workspaces

Any requests that don’t specify a workspace target the default workspace.

To target a different workspace, prefix any endpoint with the workspace name or ID:

http://localhost:8001/<WORKSPACE_NAME|ID>/<ENDPOINT>

For example, if you don’t specify a workspace, this request retrieves a list of services from the default workspace:

curl -i -X GET http://localhost:8001/services

While this request retrieves all services from the workspace SRE:

curl -i -X GET http://localhost:8001/SRE/services