API Reference
Complete endpoint reference for the API Gateway management API. All management endpoints require ADMIN role authorization. The base path is /api/v1/gateway.
Health and Status
| Method | Path | Description |
|---|---|---|
GET | /api/v1/gateway/health | Get gateway health status (public) |
Service Management
| Method | Path | Description |
|---|---|---|
GET | /api/v1/gateway/services | List all registered services |
POST | /api/v1/gateway/services | Create or update a service |
DELETE | /api/v1/gateway/services/:serviceName | Delete a service |
Route Management
| Method | Path | Description |
|---|---|---|
POST | /api/v1/gateway/services/:serviceName/routes | Create or update a route for a service |
DELETE | /api/v1/gateway/routes/:routeName | Delete a route |
Plugin Management
| Method | Path | Description |
|---|---|---|
POST | /api/v1/gateway/plugins | Enable a plugin (global, service, or route scope) |
PATCH | /api/v1/gateway/plugins/:pluginId | Update plugin configuration |
DELETE | /api/v1/gateway/plugins/:pluginId | Disable and remove a plugin |
Rate Limiting
| Method | Path | Description |
|---|---|---|
POST | /api/v1/gateway/tenants/:tenantId/rate-limit | Configure rate limiting for a tenant |
Traffic Management
| Method | Path | Description |
|---|---|---|
POST | /api/v1/gateway/services/:serviceName/canary | Configure canary traffic split |
POST | /api/v1/gateway/routes/:routeName/mirror | Configure traffic mirroring |
Upstream (Load Balancing) Management
| Method | Path | Description |
|---|---|---|
POST | /api/v1/gateway/upstreams | Create or update an upstream |
DELETE | /api/v1/gateway/upstreams/:upstreamName | Delete an upstream |
POST | /api/v1/gateway/upstreams/:upstreamName/targets | Add a target to an upstream |
GET | /api/v1/gateway/upstreams/:upstreamName/targets | List targets for an upstream |
PATCH | /api/v1/gateway/upstreams/:upstreamName/targets/:targetAddress/weight | Update target weight |
GET | /api/v1/gateway/upstreams/:upstreamName/health | Get upstream target health |
POST | /api/v1/gateway/upstreams/:upstreamName/targets/:targetAddress/healthy | Set target as healthy |
POST | /api/v1/gateway/upstreams/:upstreamName/targets/:targetAddress/unhealthy | Set target as unhealthy |
Load Balancing Presets
| Method | Path | Description |
|---|---|---|
POST | /api/v1/gateway/upstreams/preset/round-robin | Configure round-robin load balancing |
POST | /api/v1/gateway/upstreams/preset/weighted | Configure weighted load balancing |
POST | /api/v1/gateway/upstreams/preset/sticky-header | Configure sticky sessions by header |
POST | /api/v1/gateway/upstreams/preset/sticky-cookie | Configure sticky sessions by cookie |
POST | /api/v1/gateway/upstreams/preset/least-connections | Configure least-connections load balancing |
Common Response Codes
| Code | Description |
|---|---|
200 | Successful operation |
201 | Resource created |
204 | Resource deleted (no content) |
400 | Invalid request payload |
401 | Missing or invalid authentication |
403 | Insufficient permissions (requires ADMIN role) |
404 | Resource not found |
500 | Internal server error (Kong Admin API unreachable) |
Authentication
All management endpoints (except /health) require:
| Header | Value | Required |
|---|---|---|
Authorization | Bearer <JWT token> | Yes |
The JWT token must contain the ADMIN role claim.