跳到主要内容
API docs by Redocly

API7 Enterprise Admin APIs (3.10.0)

Download OpenAPI specification:Download

API7 Enterprise Admin APIs are RESTful APIs that allow you to create, configure, and manage all API7 Enterprise resources programmatically. These APIs power the API7 Dashboard and can be used directly for automation, CI/CD pipelines, and integration with external systems.

Base URL

All API paths are relative to your API7 Dashboard address, e.g. https://your-api7-dashboard:7443.

Authentication

Every request must include one of the following credentials:

  • API Key: Pass a valid API key in the X-API-KEY HTTP header.
  • Basic Auth: Use HTTP Basic Authentication with a dashboard user's credentials.

Two API Path Styles

API7 Enterprise exposes two families of endpoints:

Path prefix Purpose
/api/... Dashboard management APIs for services, gateway groups, users, roles, and all other resources.
/apisix/admin/... APISIX-compatible Admin APIs that operate on published services within a specific gateway group. Use these if you are migrating from or integrating with Apache APISIX.

Key Concepts

  • Published Service — A service deployed to a specific gateway group, actively handling live traffic.
  • Gateway Group — A logical grouping of gateway instances that share the same configuration. Resources like consumers, global rules, and published services are scoped to a gateway group.
  • Gateway Instance — An individual APISIX gateway node running inside a gateway group.
  • Consumer — An API consumer identity used for authentication and rate limiting, scoped to a gateway group.
  • Route — A traffic matching rule (host, path, HTTP method) that belongs to a service.
  • Stream Route — A Layer 4 (TCP/UDP) route for non-HTTP proxying.
  • Runtime Configuration — Per-gateway-group overrides applied to a published service (e.g., different upstreams or plugin settings).
  • Global Rule — Plugins applied to every request across an entire gateway group.
  • Secret Provider — Integration with external secret managers (HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets).

Response Format

All JSON responses follow an envelope structure:

  • Single resource: { "value": { ... } }
  • List of resources: { "list": [ ... ], "total": 42 }
  • Error: { "error_msg": "description of the error" }

Pagination is controlled via page (1-indexed) and page_size query parameters.

Published Service

Manage services deployed to a specific gateway group. Published services actively handle live API traffic.

Create a published service on a gateway group

Create a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. The payload follows APISIX conventions while operating on the same underlying service resource managed by dashboard APIs. Required IAM Permission: Action gateway:CreatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
One of
name
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

type
required
string
Default: "http"
Enum: "http" "stream"

Type of service. http corresponds to L7 service and stream corresponds to L4 service.

hosts
Array of strings [ 1 .. 32 ] items unique [ items^\*?[0-9a-zA-Z-._]+$ ]

The hosts of the service to accept incoming requests.

path_prefix
string [ 1 .. 4096 ] characters ^/

The listening path prefix of the service.

strip_path_prefix
boolean
Default: true

If true, strip the path prefix when proxying the request to the upstream.

plugins
object

Key-value pairs of plugins and their configurations on the object.

Use Upstream Nodes (object) or Use Service Registry (object)

The upstream contains necessary information for the gateway to proxy request to the backend service.

status
integer
Default: 1
Enum: 0 1

The object status. 1 means the object is active while 0 means it's inactive.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "type": "http",
  • "hosts": [
    ],
  • "path_prefix": "/test",
  • "strip_path_prefix": true,
  • "plugins": {
    },
  • "upstream": {
    },
  • "status": 0
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all published services on a gateway group

List published services through an APISIX Admin API compatible endpoint under /apisix/admin/. Use this to browse APISIX-formatted service objects in a gateway group. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "last_published" "name"

Index to order the services by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

unhealthy_nodes
Array of strings
Items Enum: "unhealthy_nodes_exists" "no_unhealthy_nodes"

Filter of services based on whether unhealthy nodes exist. unhealthy_nodes_exists filters for services where unhealthy nodes exist. no_unhealthy_nodes filters for servies where there are no unhealthy nodes.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

hosts
Array of strings[ items^\*?[0-9a-zA-Z-._]+$ ]
Example: hosts=httpbin.org
type
Array of strings
Items Enum: "http" "stream"

Type of service. http corresponds to L7 service and stream corresponds to L4 service.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a published service on a gateway group

Get one published service through an APISIX Admin API compatible endpoint under /apisix/admin/. The response keeps APISIX field conventions for migration and interoperability scenarios. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a published service without publishing

Fully update a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This replaces the stored service configuration without executing a separate publish trigger. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
One of
name
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

type
required
string
Default: "http"
Enum: "http" "stream"

Type of service. http corresponds to L7 service and stream corresponds to L4 service.

hosts
Array of strings [ 1 .. 32 ] items unique [ items^\*?[0-9a-zA-Z-._]+$ ]

The hosts of the service to accept incoming requests.

path_prefix
string [ 1 .. 4096 ] characters ^/

The listening path prefix of the service.

strip_path_prefix
boolean
Default: true

If true, strip the path prefix when proxying the request to the upstream.

plugins
object

Key-value pairs of plugins and their configurations on the object.

Use Upstream Nodes (object) or Use Service Registry (object)

The upstream contains necessary information for the gateway to proxy request to the backend service.

status
integer
Default: 1
Enum: 0 1

The object status. 1 means the object is active while 0 means it's inactive.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "type": "http",
  • "hosts": [
    ],
  • "path_prefix": "/test",
  • "strip_path_prefix": true,
  • "plugins": {
    },
  • "upstream": {
    },
  • "status": 0
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch a published service on a gateway group

Partially update a published service via JSON Patch (RFC 6902) through an APISIX Admin API compatible endpoint under /apisix/admin/. Use this for targeted field changes. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a published service on a gateway group

Delete a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Removing this object affects all APISIX-compatible references to the service in that gateway group. Required IAM Permission: Action gateway:DeletePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Get the OpenAPI Specification of a service

Get the OAS document for a service. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

apisix_service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the APISIX service.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update the OpenAPI Specification of a service

Update the OAS document for a service. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

apisix_service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the APISIX service.

Request Body schema: application/json
raw_openapi
string

The raw OpenAPI spec of the service.

Responses

Request samples

Content type
application/json
{
  • "raw_openapi": "Raw OpenAPI spec"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Create a upstream in a published service on a gateway group

Create an upstream within a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This adds backend target configuration in APISIX format. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
One of
One of
name
string [ 1 .. 65536 ] characters
Default: "default"

The upstream name.

scheme
string
Default: "http"
Enum: "http" "https" "grpc" "grpcs"

The protocol that is used for communicating with the backend service when the service type is http.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

type
string
Default: "roundrobin"
Enum: "chash" "roundrobin" "least_conn" "ewma"

Load balancing algorithm to distribute traffic.

hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

Type of value to hash on when type is chash.

key
string non-empty

The key is used when type is chash. The corresponding upstream ID is determined based on the hash_on and key values. - When hash_on is set to vars, key is required and supports built-in variables. - When hash_on is set to vars_combinations, key is required and supports a combination of built-in variables. - When hash_on is set to header, key is required and should be the name of the header. - When hash_on is set to cookie, key is required and should be the name of the cookie. - When hash_on is set to consumer, key is not required, as the hash algorithm uses the authenticated consumer name.

retries
integer [ 0 .. 65535 ]

The number of retries while passing the request to an upstream.

object

Upstream keepalive connection pool.

object

Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.

retry_timeout
number <float> >= 0
Default: 0

Timeout to continue with retries. Setting this to 0 disables the retry timeout.

pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

The approach to decide the host header before forwarding requests to an upstream.

  • pass uses the host specified in the service.
  • node uses the host specified in the upstream.
  • rewrite uses custom host.
upstream_host
string^\*?[0-9a-zA-Z-._]+$

Value to rewrite the host header to. Only used if pass_host is rewrite.

required
Array of objects

The upstream endpoints.

service_name
string [ 1 .. 256 ] characters

Service name in the service registry. Only valid for service discovery.

discovery_type
string
Enum: "kubernetes" "nacos" "consul"

Type of service discovery. Only valid for service discovery.

object

Service discovery arguments. Only valid for service discovery.

object or object
Deprecated

Replace with client_certificate and ca_certificates

client_certificate
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The object ID.

ca_certificates
Array of strings[ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

CA certificates.

tls_verify
boolean

If true, verify TLS.

Active Check (object) or Passive Check (object)

Health check configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "us-west-rsc",
  • "scheme": "http",
  • "desc": "Object description.",
  • "labels": {
    },
  • "type": "chash",
  • "hash_on": "vars",
  • "key": "$host",
  • "retries": 50,
  • "keepalive_pool": {
    },
  • "timeout": {
    },
  • "retry_timeout": 0,
  • "pass_host": "pass",
  • "upstream_host": "httpbin.org",
  • "nodes": [
    ],
  • "service_name": "<ServiceRegistryID>/public/group/httpbin",
  • "discovery_type": "nacos",
  • "discovery_args": {
    },
  • "tls": {
    },
  • "client_certificate": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101",
  • "ca_certificates": [
    ],
  • "tls_verify": true,
  • "checks": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all upstreams in a published service on a gateway group

List upstreams attached to a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Use this to inspect backend pools and their current settings. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

order_by
string
Default: "created_at"
Value: "created_at"
direction
string
Default: "asc"
Value: "asc"

Order to list the routes by. The sorting index follows the configuration of order_by.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a upstream in a published service on a gateway group

Get one upstream in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. The response uses APISIX-style upstream structure. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

upstream_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the upstream.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a upstream in a published service on a gateway group

Fully update an upstream in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Submit the complete upstream object to replace existing configuration. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

upstream_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the upstream.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
One of
One of
name
string [ 1 .. 65536 ] characters
Default: "default"

The upstream name.

scheme
string
Default: "http"
Enum: "http" "https" "grpc" "grpcs"

The protocol that is used for communicating with the backend service when the service type is http.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

type
string
Default: "roundrobin"
Enum: "chash" "roundrobin" "least_conn" "ewma"

Load balancing algorithm to distribute traffic.

hash_on
string
Default: "vars"
Enum: "vars" "header" "cookie" "consumer" "vars_combinations"

Type of value to hash on when type is chash.

key
string non-empty

The key is used when type is chash. The corresponding upstream ID is determined based on the hash_on and key values. - When hash_on is set to vars, key is required and supports built-in variables. - When hash_on is set to vars_combinations, key is required and supports a combination of built-in variables. - When hash_on is set to header, key is required and should be the name of the header. - When hash_on is set to cookie, key is required and should be the name of the cookie. - When hash_on is set to consumer, key is not required, as the hash algorithm uses the authenticated consumer name.

retries
integer [ 0 .. 65535 ]

The number of retries while passing the request to an upstream.

object

Upstream keepalive connection pool.

object

Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.

retry_timeout
number <float> >= 0
Default: 0

Timeout to continue with retries. Setting this to 0 disables the retry timeout.

pass_host
string
Default: "pass"
Enum: "pass" "node" "rewrite"

The approach to decide the host header before forwarding requests to an upstream.

  • pass uses the host specified in the service.
  • node uses the host specified in the upstream.
  • rewrite uses custom host.
upstream_host
string^\*?[0-9a-zA-Z-._]+$

Value to rewrite the host header to. Only used if pass_host is rewrite.

required
Array of objects

The upstream endpoints.

service_name
string [ 1 .. 256 ] characters

Service name in the service registry. Only valid for service discovery.

discovery_type
string
Enum: "kubernetes" "nacos" "consul"

Type of service discovery. Only valid for service discovery.

object

Service discovery arguments. Only valid for service discovery.

object or object
Deprecated

Replace with client_certificate and ca_certificates

client_certificate
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The object ID.

ca_certificates
Array of strings[ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

CA certificates.

tls_verify
boolean

If true, verify TLS.

Active Check (object) or Passive Check (object)

Health check configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "us-west-rsc",
  • "scheme": "http",
  • "desc": "Object description.",
  • "labels": {
    },
  • "type": "chash",
  • "hash_on": "vars",
  • "key": "$host",
  • "retries": 50,
  • "keepalive_pool": {
    },
  • "timeout": {
    },
  • "retry_timeout": 0,
  • "pass_host": "pass",
  • "upstream_host": "httpbin.org",
  • "nodes": [
    ],
  • "service_name": "<ServiceRegistryID>/public/group/httpbin",
  • "discovery_type": "nacos",
  • "discovery_args": {
    },
  • "tls": {
    },
  • "client_certificate": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101",
  • "ca_certificates": [
    ],
  • "tls_verify": true,
  • "checks": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch a upstream in a published service on a gateway group

Partially update an upstream in a published service via JSON Patch (RFC 6902) through an APISIX Admin API compatible endpoint under /apisix/admin/. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

upstream_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the upstream.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a upstream in a published service on a gateway group

Delete an upstream from a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This updates service backend routing targets without deleting the service itself. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

upstream_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the upstream.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Generate an OpenAPI specification from published services in a gateway group

Export published service definitions from a specific gateway group as an OpenAPI 3.0 specification document.

Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
scope
string
Enum: "partial" "all"

Scope of the service.

Request Body schema: application/json
service_ids
Array of strings[ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

The service ID list.

required
object

API metadata.

Array of objects

An array of one or more base servers in the exported API definition.

Responses

Request samples

Content type
application/json
{
  • "service_ids": [
    ],
  • "info": {
    },
  • "servers": []
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Import services based on OpenAPI Specification

Import an OpenAPI specification directly into published services for a gateway group. This operation creates runtime service resources scoped to the target gateway group.

Required IAM Permission: Action gateway:CreatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

type
string
Default: "http"
Value: "http"

Type of service.

Array of objects non-empty unique

Route configurations.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "type": "http",
  • "routes": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Convert OpenAPI Specification to service and route resources

Convert a given OpenAPI Specification into service and route resource structures without creating those resources. Use this endpoint for preview, validation, and transformation workflows before import.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
raw_openapi
required
string

The raw OpenAPI content.

Responses

Request samples

Content type
application/json
{
  • "raw_openapi": "Raw OpenAPI spec"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Create a route in a published service on a gateway group

Create a route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This adds APISIX-formatted HTTP routing rules on shared dashboard resources. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

methods
Array of strings [ 1 .. 9 ] items unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE"

The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.

vars
Array of any

Conditions in the format of APISIX expressions to match requests to routes. Case sensitive when matching a cookie name.

paths
required
Array of strings [ 1 .. 64 ] items [ items [ 1 .. 4096 ] characters ]

The URL path(s) (after the service's path_prefix) that the route will listen to. Each path should start with a /.

priority
integer
Default: 0

Priority of the route. A higher value corresponds to a higher priority. If different Routes matches to the same URI, then the Route with the highest priority will be matched.

enable_websocket
boolean or null

If true, enable Websocket proxying for the route.

object

Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "methods": [
    ],
  • "vars": [
    ],
  • "paths": [
    ],
  • "priority": 0,
  • "enable_websocket": true,
  • "timeout": {
    },
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all routes in a published service

List routes in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Use pagination and filters to inspect APISIX-compatible route entries. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: service_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a route in a published service on a gateway group

Get one route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This returns the route with APISIX field format. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a route in a published service on a gateway group

Fully update a route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Use this when replacing the entire route object. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

methods
Array of strings [ 1 .. 9 ] items unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE"

The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.

vars
Array of any

Conditions in the format of APISIX expressions to match requests to routes. Case sensitive when matching a cookie name.

paths
required
Array of strings [ 1 .. 64 ] items [ items [ 1 .. 4096 ] characters ]

The URL path(s) (after the service's path_prefix) that the route will listen to. Each path should start with a /.

priority
integer
Default: 0

Priority of the route. A higher value corresponds to a higher priority. If different Routes matches to the same URI, then the Route with the highest priority will be matched.

enable_websocket
boolean or null

If true, enable Websocket proxying for the route.

object

Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "methods": [
    ],
  • "vars": [
    ],
  • "paths": [
    ],
  • "priority": 0,
  • "enable_websocket": true,
  • "timeout": {
    },
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch a route in a published service on a gateway group

Partially update a route in a published service via JSON Patch (RFC 6902) through an APISIX Admin API compatible endpoint under /apisix/admin/. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a route in a published service on a gateway group

Delete a route from a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Requests that matched this rule will no longer be routed by it. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Create a stream route in a published service on a gateway group

Create a stream route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This configures APISIX-style TCP/UDP traffic matching rules. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

Client address filter. If the client request does not originate from remote_addr, the request will not be forwarded to the stream server.

(IPAddress (IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string))) or Domain (string)

Stream server address.

server_port
integer <= 65535

Stream server port.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "remote_addr": "127.0.0.1",
  • "server_addr": "mysql",
  • "server_port": 3306,
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all stream routes in a published service on a gateway group

List stream routes in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Use this for visibility into current L4 routing rules. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: service_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a stream route in a published service on a gateway group

Get one stream route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. The returned object matches APISIX stream-route conventions. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
stream_route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published stream route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a stream route in a published service on a gateway group

Fully update a stream route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This replaces the existing stream-route configuration. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
stream_route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published stream route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

Client address filter. If the client request does not originate from remote_addr, the request will not be forwarded to the stream server.

(IPAddress (IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string))) or Domain (string)

Stream server address.

server_port
integer <= 65535

Stream server port.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "remote_addr": "127.0.0.1",
  • "server_addr": "mysql",
  • "server_port": 3306,
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a stream route in a published service on a gateway group

Delete a stream route from a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This removes a specific L4 route while preserving other service objects. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
stream_route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published stream route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Get healthcheck status for the upstream of a published service on a gateway group, if upstream_id is not provided, get healthcheck status for default upstream of this service

Retrieve upstream node health check results for a published service in a gateway group. If no upstream ID is provided, the status of the service's default upstream is returned.

Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

apisix_service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the APISIX service.

query Parameters
upstream_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: upstream_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the upstream.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all published services connected to a service registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "publish_time" "name"

Index to order published services by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Route

Manage HTTP routes (host, path, method matching rules) that belong to a service.

Create a route in a published service on a gateway group

Create a route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This adds APISIX-formatted HTTP routing rules on shared dashboard resources. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

methods
Array of strings [ 1 .. 9 ] items unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE"

The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.

vars
Array of any

Conditions in the format of APISIX expressions to match requests to routes. Case sensitive when matching a cookie name.

paths
required
Array of strings [ 1 .. 64 ] items [ items [ 1 .. 4096 ] characters ]

The URL path(s) (after the service's path_prefix) that the route will listen to. Each path should start with a /.

priority
integer
Default: 0

Priority of the route. A higher value corresponds to a higher priority. If different Routes matches to the same URI, then the Route with the highest priority will be matched.

enable_websocket
boolean or null

If true, enable Websocket proxying for the route.

object

Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "methods": [
    ],
  • "vars": [
    ],
  • "paths": [
    ],
  • "priority": 0,
  • "enable_websocket": true,
  • "timeout": {
    },
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all routes in a published service

List routes in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Use pagination and filters to inspect APISIX-compatible route entries. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: service_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a route in a published service on a gateway group

Get one route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This returns the route with APISIX field format. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a route in a published service on a gateway group

Fully update a route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Use this when replacing the entire route object. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

methods
Array of strings [ 1 .. 9 ] items unique
Items Enum: "GET" "POST" "PUT" "DELETE" "PATCH" "HEAD" "OPTIONS" "CONNECT" "TRACE"

The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.

vars
Array of any

Conditions in the format of APISIX expressions to match requests to routes. Case sensitive when matching a cookie name.

paths
required
Array of strings [ 1 .. 64 ] items [ items [ 1 .. 4096 ] characters ]

The URL path(s) (after the service's path_prefix) that the route will listen to. Each path should start with a /.

priority
integer
Default: 0

Priority of the route. A higher value corresponds to a higher priority. If different Routes matches to the same URI, then the Route with the highest priority will be matched.

enable_websocket
boolean or null

If true, enable Websocket proxying for the route.

object

Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "methods": [
    ],
  • "vars": [
    ],
  • "paths": [
    ],
  • "priority": 0,
  • "enable_websocket": true,
  • "timeout": {
    },
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch a route in a published service on a gateway group

Partially update a route in a published service via JSON Patch (RFC 6902) through an APISIX Admin API compatible endpoint under /apisix/admin/. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a route in a published service on a gateway group

Delete a route from a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Requests that matched this rule will no longer be routed by it. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Stream Route

Manage Layer 4 (TCP/UDP) stream routes for non-HTTP proxying within a service.

Create a stream route in a published service on a gateway group

Create a stream route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This configures APISIX-style TCP/UDP traffic matching rules. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

Client address filter. If the client request does not originate from remote_addr, the request will not be forwarded to the stream server.

(IPAddress (IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string))) or Domain (string)

Stream server address.

server_port
integer <= 65535

Stream server port.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "remote_addr": "127.0.0.1",
  • "server_addr": "mysql",
  • "server_port": 3306,
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all stream routes in a published service on a gateway group

List stream routes in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. Use this for visibility into current L4 routing rules. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: service_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a stream route in a published service on a gateway group

Get one stream route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. The returned object matches APISIX stream-route conventions. Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
stream_route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published stream route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

with_publish_info
boolean
Default: false

If true, include publish information in the response, such as apisix_route_id, route_version_id, and service_version_id. The additional information is only useful for the Dashboard and not for API users.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a stream route in a published service on a gateway group

Fully update a stream route in a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This replaces the existing stream-route configuration. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
stream_route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published stream route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 65536 ] characters

The object name.

object

Key-value pairs of labels.

desc
string <= 65536 characters

The object description.

IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string)

Client address filter. If the client request does not originate from remote_addr, the request will not be forwarded to the stream server.

(IPAddress (IPv4 (string) or IPv4/CIDR (string) or IPv6 (string) or IPv6/CIDR (string))) or Domain (string)

Stream server address.

server_port
integer <= 65535

Stream server port.

plugins
object

Key-value pairs of plugins and their configurations on the object.

service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$

The service ID.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "labels": {
    },
  • "desc": "Object description.",
  • "remote_addr": "127.0.0.1",
  • "server_addr": "mysql",
  • "server_port": 3306,
  • "plugins": {
    },
  • "service_id": "b32e678e-7f6b-4a50-b113-550621ed4c01"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a stream route in a published service on a gateway group

Delete a stream route from a published service through an APISIX Admin API compatible endpoint under /apisix/admin/. This removes a specific L4 route while preserving other service objects. Required IAM Permission: Action gateway:UpdatePublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
stream_route_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published stream route.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Consumer

Manage API consumer identities used for authentication, authorization, and rate limiting. Consumers are scoped to a gateway group.

Create a consumer on a gateway group

IAM Action: gateway:CreateConsumer, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$

The unique identifier of the consumer.

plugins
object

Key-value pairs of plugins and their configurations on the object.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe",
  • "plugins": {
    },
  • "desc": "Object description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all consumers on a gateway group

IAM Action: gateway:GetConsumer, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "username"

Index to order consumers by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a consumer on a gateway group

IAM Action: gateway:GetConsumer, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a consumer on a gateway group

IAM Action: gateway:UpdateConsumer, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$

The unique identifier of the consumer.

plugins
object

Key-value pairs of plugins and their configurations on the object.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "username": "johndoe",
  • "plugins": {
    },
  • "desc": "Object description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a consumer

IAM Action: gateway:DeleteConsumer, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Update a consumer on a gateway group

IAM Action: gateway:UpdateConsumer, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Create a consumer credential on a gateway group

IAM Action: gateway:CreateConsumerCredential, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 100 ] characters

The object name.

required
key-auth (object) or basic-auth (object) or hmac-auth (object) or jwt-auth (object) = 1 properties

Plugin configuration.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "plugins": {
    },
  • "desc": "Object description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all consumer credentials on a gateway group

IAM Action: gateway:GetConsumerCredential, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

query Parameters
plugin_name
string [ 1 .. 100 ] characters
Example: plugin_name=us-west-rsc

the plugin name of the consumer credential.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "name"

Index to order consumers by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a consumer credential on a gateway group

IAM Action: gateway:GetConsumerCredential, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

credential_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the consumer credential.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a consumer credential on a gateway group

IAM Action: gateway:UpdateConsumerCredential, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

credential_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the consumer credential.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
required
string [ 1 .. 100 ] characters

The object name.

required
key-auth (object) or basic-auth (object) or hmac-auth (object) or jwt-auth (object) = 1 properties

Plugin configuration.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "plugins": {
    },
  • "desc": "Object description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a consumer credential

IAM Action: gateway:DeleteConsumerCredential, Resource: arn:api7:gateway:gatewaygroup/%s/consumer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
username
required
string [ 1 .. 512 ] characters ^[a-zA-Z0-9_\-]+$
Example: johndoe

The unique identifier of the consumer.

credential_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the consumer credential.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Gateway Group

Manage gateway groups — logical clusters of gateway instances sharing configuration. Resources like consumers and published services are scoped to a gateway group.

Check service route conflicts in a gateway group

Check for duplicate or overlapping routes among services within a gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
Array of objects
Array
id
string
name
string
hosts
Array of strings
path_prefix
string
Array of objects

Responses

Request samples

Content type
application/json
{
  • "services": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all gateway instances on a gateway group

IAM Action: gateway:GetGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
order_by
string
Default: "last_heartbeat_time"
Enum: "created_at" "last_heartbeat_time"

Index to order gateway instances by.

status
string
Enum: "Healthy" "OutOfSync" "LostConnection" "Offline"

The value of the instance status.

compatibility
string
Enum: "Compatible" "Incompatible" "PartiallyCompatible"

The compatibility of the gateway instance version.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Count the number of gateway instances by status in a gateway group

IAM Action: gateway:GetGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
field
required
string
Value: "status"

Field to count by.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

Export the gateway instance core usage

The gateway instance’s core usage is exported hourly within the specified time interval.
IAM Action: gateway:GetGatewayInstanceCore, Resource: arn:api7:gateway:gatewaygroup/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
begin_at
required
integer <int32>

The start time to export the gateway instance core usage.

end_at
required
integer <int32>

The end time to export the gateway instance core usage.

Responses

Response samples

Content type
text/csv
time,max_dp_cores
1749132000,9
1749128400,9
1749124800,9
1749121200,9
1749117600,9
1749114000,9
1749110400,9
1749106800,17
1749103200,1
1749099600,1
1749096000,1
1749092400,1
1749088800,1

List all gateway groups

IAM Action: gateway:GetGatewayGroup, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

name
string >= 1
Example: name=default

Gateway group name.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a gateway group

IAM Action: gateway:CreateGatewayGroup, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
type
string
Default: "api7_gateway"
Enum: "api7_gateway" "api7_ingress_controller"
name
required
string [ 1 .. 100 ] characters

The object name.

description
string

Gateway group description.

object

Key-value pairs of labels.

enforce_service_publishing
boolean

If ture, bypass version control and rollback when updating services directly on a gateway group.

Responses

Request samples

Content type
application/json
{
  • "type": "api7_gateway",
  • "name": "us-west-rsc",
  • "description": "Gateway group description.",
  • "labels": {
    },
  • "enforce_service_publishing": true
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Count resources by type in each gateway group

Authorizations:
APIKeyAuthBasicAuth
path Parameters
resource_type
required
string
Enum: "ssl" "consumer" "gateway_instance"

Resource type.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List SSL Usage in a gateway group

IAM Action: gateway:GetSSLCertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

ssl_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SSL object.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List SNI Usage in a gateway group

IAM Action: gateway:GetSNI, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

sni_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SNI object.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List Certificate Usage in a gateway group

IAM Action: gateway:GetCertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the Certificate.

query Parameters
resource_type
string
Default: "sni"
Enum: "sni" "upstream"

Type of resource referencing the certificate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List CA Certificate Usage in a gateway group

IAM Action: gateway:GetCACertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

ca_certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the certificate.

query Parameters
resource_type
string
Default: "sni"
Enum: "sni" "upstream"

Type of resource referencing the certificate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Check if a certificate exists in a gateway group

IAM Action: gateway:GetCACertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
Certificate Reference (string) or Certificate Content (string)

Certificate.

One of
string (Certificate Reference) ^\$(secret|env|ENV)://

Path to the certificate in environment variable or secret manager.

Responses

Request samples

Content type
application/json
{
  • "cert": "$secret://aws/john/apisix-secrets/john-key-auth"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Check if a CA certificate exists in a gateway group

IAM Action: gateway:GetCACertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
cert
string [ 1 .. 65536 ] characters ^[^\$]

The certificate in PEM format.

Responses

Request samples

Content type
application/json
{
  • "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List Secret Provider Usage in a gateway group

IAM Action: gateway:GetSecretProvider, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

secret_provider
required
string
Enum: "vault" "aws" "kubernetes"

Secret provider.

secret_provider_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Secret provider ID.

query Parameters
resource_type
string
Enum: "consumer" "service" "route" "ssl" "global_rule" "consumer_credential" "certificate"

Resource type.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Delete a gateway group

IAM Action: gateway:DeleteGatewayGroup, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
""

Update a gateway group

IAM Action: gateway:UpdateGatewayGroup, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

The object name.

description
required
string

Gateway group description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "description": "Gateway group description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a gateway group

IAM Action: gateway:GetGatewayGroup, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get resource paths

Resolve resource IDs to ordered business resource paths on demand.
IAM Action: gateway:GetGatewayGroup, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
required
Array of objects <= 200 items

Resources to resolve.

Array (<= 200 items)
resource_type
string

Resource type to resolve.

resource_id
string

Resource ID to resolve.

Responses

Request samples

Content type
application/json
{
  • "resources": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get the admin key for a gateway group.

IAM Action: gateway:GetAdminKey, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Generate an admin key for a gateway group

IAM Action: gateway:UpdateGatewayGroup, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Generate a script to install the gateway instance by Docker

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

https_port
integer
Default: 9443

The HTTPS port of the gateway.

name
string non-empty

The hostname of the gateway.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='["https://12.12.123.123:31344"]' \
  -e API7_GATEWAY_GROUP_SHORT_ID=tabqbdwnahkqo \
  -e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
  MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
  ...
  -----END CERTIFICATE-----" \
  -e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
  MC4CAQAwBQYDK2VwBCIEIG1Q/eJDdTZ4krnd7ezprKcZ2ASeTSrhpWglMzh9d0Hs
  -----END PRIVATE KEY-----" \
  -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
  MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
  ...
  -----END CERTIFICATE-----" \
  -e API7_CONTROL_PLANE_SNI="api7ee3-dp-manager" \
  -p 9080:9080 \
  -p 9443:9443 \
  api7/api7-ee-3-gateway:latest

Generate a script to install the gateway instance by Docker Compose

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

https_port
integer
Default: 9443

The HTTPS port of the gateway.

name
string non-empty
Default: "api7-ee-3-gateway"

The name of the docker compose container and service.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
services:
  gateway:
    image: api7/api7-ee-3-gateway:latest
    container_name: gateway
    hostname: gateway
    restart: always
    ports:
      - "9080:9080"
      - "9443:9443"
    environment:
      API7_DP_MANAGER_ENDPOINTS: '["https://12.12.123.123:31344"]'
      API7_GATEWAY_GROUP_SHORT_ID: "oybqauztthfao"
      API7_DP_MANAGER_SNI: "api7ee3-dp-manager"
      API7_DP_MANAGER_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
        ...
        -----END CERTIFICATE-----

      API7_DP_MANAGER_KEY: |
        -----BEGIN PRIVATE KEY-----
        MC4CAQAwBQYDK2VwBCIEINc8Pn0gPTq2keIBs4tzdemXxhe1Qq7xAxtJ8nve6Mg3
        -----END PRIVATE KEY-----

      API7_CONTROL_PLANE_CA: |
        -----BEGIN CERTIFICATE-----
        MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
        ...
        -----END CERTIFICATE-----

Generate a script to install the gateway instance by Helm in Kubernetes

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

extra_values[]
Array of strings
Example: extra_values[]=a=b&extra_values[]=c=d

Extra values to be passed to the Helm chart, in the form of key=value.

Responses

Response samples

Content type
text/plain
helm repo add api7 https://charts.api7.ai
helm repo update
cat > /tmp/tls.crt <<EOF
-----BEGIN CERTIFICATE-----
MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
...
-----END CERTIFICATE-----
EOF
cat > /tmp/tls.key <<EOF
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQ...AuNANhyrM9qUepu5ZGtVgXnX
-----END PRIVATE KEY-----
EOF
cat > /tmp/ca.crt <<EOF
-----BEGIN CERTIFICATE-----
MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIBeDCCASqgAwIBAgIRAPNxgFOmSXOwtIdZOgynsLswBQYDK2VwMEQxCzAJBgNV
...
-----END CERTIFICATE-----
EOF
kubectl create namespace default --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret generic -n default name-tls --from-file=tls.crt=/tmp/tls.crt --from-file=tls.key=/tmp/tls.key --from-file=ca.crt=/tmp/ca.crt
helm upgrade --install -n default --create-namespace name api7/gateway \
  --set "etcd.auth.tls.enabled=true" \
  --set "etcd.auth.tls.existingSecret=name-tls" \
  --set "etcd.auth.tls.certFilename=tls.crt" \
  --set "etcd.auth.tls.certKeyFilename=tls.key" \
  --set "etcd.auth.tls.sni=api7ee3-dp-manager" \
  --set "etcd.auth.tls.verify=true" \
  --set "gateway.tls.existingCASecret=name-tls" \
  --set "gateway.tls.certCAFilename=ca.crt" \
  --set "apisix.extraEnvVars[0].name=API7_GATEWAY_GROUP_SHORT_ID" \
  --set "apisix.extraEnvVars[0].value=tabqbdwnahkqo" \
  --set "etcd.host[0]=https://12.12.123.123:31344" \
  --set "apisix.resources.limits.cpu=4" \
  --set "apisix.resources.limits.memory=7168Mi" \
  --set "apisix.replicaCount=1" \
  --set "apisix.image.repository=api7/api7-ee-3-gateway" \
  --set "apisix.image.tag=latest"

Generate a values file for the gateway's Kubernetes Helm chart

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

Responses

Response samples

Content type
text/plain
apiVersion: v1
data:
  tls.crt: LS0tLS1CRUdJTiB...
  tls.key: LS0tLS1CRUdJTiB...
  ca.crt: LS0tLS1CRUdJTiB...
kind: Secret
metadata:
  name: name-tls
  namespace: default
type: kubernetes.io/tls
---
apisix:
  replicaCount: 1
  image:
    repository: api7/api7-ee-3-gateway
    tag: dev
  extraEnvVars:
  - name: API7_GATEWAY_GROUP_SHORT_ID
    value: "tabqbdwnahkqo"
etcd:
  host:
  - "https://12.12.123.123:31344"
  auth:
    tls:
      enabled: true
      existingSecret: name-tls
      certFilename: tls.crt
      certKeyFilename: tls.key
      sni: api7ee3-dp-manager
      verify: true
gateway:
  tls:
    existingCASecret: name-tls
    certCAFilename: ca.crt

Generate a script to install gateway API resources for ingress gateway group

IAM Action: gateway:GetAdminKey, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
name
required
string

Ingress resource name.

namespace
required
string

Namespace to install the ingress resources.

type
string
Default: "gateway-api"
Enum: "gateway-api" "ingress" "ingress-v1beta1"

Responses

Response samples

Content type
text/plain
kubectl create namespace default --dry-run=client -o yaml | kubectl apply -f -
echo "
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: apisix
spec:
  controllerName: apisix.apache.org/apisix-ingress-controller
---
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  name: name
spec:
  provider:
    type: ControlPlane
    controlPlane:
      endpoints:
        - ["12.12.123.123"]
      auth:
        type: AdminKey
        adminKey:
          value: a7adm-ZgR85iE...
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: apisix
spec:
  gatewayClassName: apisix
  listeners:
    - name: http
      protocol: HTTP
      port: 80
  infrastructure:
    parametersRef:
      group: apisix.apache.org
      kind: GatewayProxy
      name: name
" | kubectl apply -f - -n default

Generate script to install the gateway api resources for ingress gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
namespace
string

Namespace to install the ingress controller.

name
string

Helm release name.

Responses

Response samples

Content type
application/json
{
  • "value": { },
  • "error_msg": "error message"
}

Issue a data plane certificate on a gateway group

Issue a client TLS certificate for data plane instances in the specified gateway group to authenticate with the control plane. Use this during gateway bootstrap or certificate rotation.

Required IAM Permission: Action gateway:CreateGatewayInstance, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

Responses

Request samples

Content type
application/json
{
  • "validity_period": 3650
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get healthcheck status for the upstream of a published service on a gateway group, if upstream_id is not provided, get healthcheck status for default upstream of this service

Retrieve upstream node health check results for a published service in a gateway group. If no upstream ID is provided, the status of the service's default upstream is returned.

Required IAM Permission: Action gateway:GetPublishedService, Resource arn:api7:gateway:gatewaygroup/%s/publishedservice/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

apisix_service_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the APISIX service.

query Parameters
upstream_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: upstream_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the upstream.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all service registry connections on a gateway group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "last_connect_time"

Index to order service registry connections by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a service registry connection on a gateway group

IAM Action: gateway:ConnectServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
One of
name
string [ 1 .. 100 ] characters

The object name.

description
string

Service registry description.

object

Health check configurations.

type
required
string
Value: "kubernetes"

The kubernetes service type.

required
object

Kubernetes service registry configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "sample-service-registry",
  • "description": "service registry description",
  • "health_check": {
    },
  • "type": "kubernetes",
  • "kubernetes_config": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Create a token for all gateway instances in a gateway group

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
only_token
boolean

If true, the response will only contain the token.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a service registry connection on a gateway group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a service registry connection on a gateway group

IAM Action: gateway:UpdateServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
required
One of
name
string [ 1 .. 100 ] characters

The object name.

description
string

Service registry description.

object

Health check configurations.

type
required
string
Value: "kubernetes"

The kubernetes service type.

required
object

Kubernetes service registry configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "sample-service-registry",
  • "description": "service registry description",
  • "health_check": {
    },
  • "type": "kubernetes",
  • "kubernetes_config": {
    }
}

Response samples

Content type
application/json
{
  • "value": { }
}

Delete a service registry connection on a gateway group

IAM Action: gateway:DisconnectServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
""

List all published services connected to a service registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "publish_time" "name"

Index to order published services by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List all internal services in a Kubernetes service registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all namespaces in a Nacos service registry

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List all groups in a Nacos namespace

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

nacos_namespace
required
string >= 1
Example: public

Nacos namespace name.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 5
}

List all internal services in a Nacos group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

nacos_namespace
required
string >= 1
Example: public

Nacos namespace name.

nacos_group
required
string >= 1
Example: DEFAULT_GROUP

Nacos group.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 5
}

Get all instance metadata of a Nacos services registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

nacos_namespace
required
string >= 1
Example: public

Nacos namespace name.

nacos_group
required
string >= 1
Example: DEFAULT_GROUP

Nacos group.

nacos_service
required
string >= 1
Example: api7ee3-keycloak

Nacos service.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 3,
  • "value": {
    }
}

List all datacenters in a Consul service registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 2
}

List all services in a Consul datacenter

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

consul_datacenter
required
string >= 1
Example: dc1

Consul datacenter name.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 3
}

Get all instance metadata of a Consul service

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

consul_datacenter
required
string >= 1
Example: dc1

Consul datacenter name.

consul_service
required
string >= 1
Example: web

Consul service name.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get health check history of a service registry connection on a gateway group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "connect_time"
Value: "connect_time"

Index to order health check history by.

status
Array of strings
Items Enum: "healthy" "lost_connection" "connecting"

Service registry connection status.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Gateway Instance

View and manage individual APISIX gateway nodes running within a gateway group. Monitor instance health, status, and resource usage.

List all gateway instances of all gateway groups

IAM Action: gateway:GetGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
string >= 1

Gateway group ID.

order_by
string
Default: "last_heartbeat_time"
Enum: "created_at" "last_heartbeat_time"

Index to order gateway instances by.

status
string
Enum: "Healthy" "OutOfSync" "LostConnection" "Offline"

The value of the instance status.

compatibility
string
Enum: "Compatible" "Incompatible" "PartiallyCompatible"

The compatibility of the gateway instance version.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List all gateway instances on a gateway group

IAM Action: gateway:GetGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
order_by
string
Default: "last_heartbeat_time"
Enum: "created_at" "last_heartbeat_time"

Index to order gateway instances by.

status
string
Enum: "Healthy" "OutOfSync" "LostConnection" "Offline"

The value of the instance status.

compatibility
string
Enum: "Compatible" "Incompatible" "PartiallyCompatible"

The compatibility of the gateway instance version.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Count the number of gateway instances by status in a gateway group

IAM Action: gateway:GetGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
field
required
string
Value: "status"

Field to count by.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

List gateway instances cores of all gateway groups

IAM Action: gateway:GetGatewayInstanceCore, Resource: arn:api7:gateway:gatewaygroup/*

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Export the gateway instance core usage

The gateway instance’s core usage is exported hourly within the specified time interval.
IAM Action: gateway:GetGatewayInstanceCore, Resource: arn:api7:gateway:gatewaygroup/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
begin_at
required
integer <int32>

The start time to export the gateway instance core usage.

end_at
required
integer <int32>

The end time to export the gateway instance core usage.

Responses

Response samples

Content type
text/csv
time,max_dp_cores
1749132000,9
1749128400,9
1749124800,9
1749121200,9
1749117600,9
1749114000,9
1749110400,9
1749106800,17
1749103200,1
1749099600,1
1749096000,1
1749092400,1
1749088800,1

Generate a script to install the gateway instance by Docker

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

https_port
integer
Default: 9443

The HTTPS port of the gateway.

name
string non-empty

The hostname of the gateway.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='["https://12.12.123.123:31344"]' \
  -e API7_GATEWAY_GROUP_SHORT_ID=tabqbdwnahkqo \
  -e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
  MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
  ...
  -----END CERTIFICATE-----" \
  -e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
  MC4CAQAwBQYDK2VwBCIEIG1Q/eJDdTZ4krnd7ezprKcZ2ASeTSrhpWglMzh9d0Hs
  -----END PRIVATE KEY-----" \
  -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
  MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
  ...
  -----END CERTIFICATE-----" \
  -e API7_CONTROL_PLANE_SNI="api7ee3-dp-manager" \
  -p 9080:9080 \
  -p 9443:9443 \
  api7/api7-ee-3-gateway:latest

Generate a script to install the gateway instance by Docker Compose

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

https_port
integer
Default: 9443

The HTTPS port of the gateway.

name
string non-empty
Default: "api7-ee-3-gateway"

The name of the docker compose container and service.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
services:
  gateway:
    image: api7/api7-ee-3-gateway:latest
    container_name: gateway
    hostname: gateway
    restart: always
    ports:
      - "9080:9080"
      - "9443:9443"
    environment:
      API7_DP_MANAGER_ENDPOINTS: '["https://12.12.123.123:31344"]'
      API7_GATEWAY_GROUP_SHORT_ID: "oybqauztthfao"
      API7_DP_MANAGER_SNI: "api7ee3-dp-manager"
      API7_DP_MANAGER_CERT: |
        -----BEGIN CERTIFICATE-----
        MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
        ...
        -----END CERTIFICATE-----

      API7_DP_MANAGER_KEY: |
        -----BEGIN PRIVATE KEY-----
        MC4CAQAwBQYDK2VwBCIEINc8Pn0gPTq2keIBs4tzdemXxhe1Qq7xAxtJ8nve6Mg3
        -----END PRIVATE KEY-----

      API7_CONTROL_PLANE_CA: |
        -----BEGIN CERTIFICATE-----
        MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
        ...
        -----END CERTIFICATE-----

Generate a script to install the gateway instance by Helm in Kubernetes

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

extra_values[]
Array of strings
Example: extra_values[]=a=b&extra_values[]=c=d

Extra values to be passed to the Helm chart, in the form of key=value.

Responses

Response samples

Content type
text/plain
helm repo add api7 https://charts.api7.ai
helm repo update
cat > /tmp/tls.crt <<EOF
-----BEGIN CERTIFICATE-----
MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI
...
-----END CERTIFICATE-----
EOF
cat > /tmp/tls.key <<EOF
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQ...AuNANhyrM9qUepu5ZGtVgXnX
-----END PRIVATE KEY-----
EOF
cat > /tmp/ca.crt <<EOF
-----BEGIN CERTIFICATE-----
MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIBeDCCASqgAwIBAgIRAPNxgFOmSXOwtIdZOgynsLswBQYDK2VwMEQxCzAJBgNV
...
-----END CERTIFICATE-----
EOF
kubectl create namespace default --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret generic -n default name-tls --from-file=tls.crt=/tmp/tls.crt --from-file=tls.key=/tmp/tls.key --from-file=ca.crt=/tmp/ca.crt
helm upgrade --install -n default --create-namespace name api7/gateway \
  --set "etcd.auth.tls.enabled=true" \
  --set "etcd.auth.tls.existingSecret=name-tls" \
  --set "etcd.auth.tls.certFilename=tls.crt" \
  --set "etcd.auth.tls.certKeyFilename=tls.key" \
  --set "etcd.auth.tls.sni=api7ee3-dp-manager" \
  --set "etcd.auth.tls.verify=true" \
  --set "gateway.tls.existingCASecret=name-tls" \
  --set "gateway.tls.certCAFilename=ca.crt" \
  --set "apisix.extraEnvVars[0].name=API7_GATEWAY_GROUP_SHORT_ID" \
  --set "apisix.extraEnvVars[0].value=tabqbdwnahkqo" \
  --set "etcd.host[0]=https://12.12.123.123:31344" \
  --set "apisix.resources.limits.cpu=4" \
  --set "apisix.resources.limits.memory=7168Mi" \
  --set "apisix.replicaCount=1" \
  --set "apisix.image.repository=api7/api7-ee-3-gateway" \
  --set "apisix.image.tag=latest"

Generate a values file for the gateway's Kubernetes Helm chart

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

Responses

Response samples

Content type
text/plain
apiVersion: v1
data:
  tls.crt: LS0tLS1CRUdJTiB...
  tls.key: LS0tLS1CRUdJTiB...
  ca.crt: LS0tLS1CRUdJTiB...
kind: Secret
metadata:
  name: name-tls
  namespace: default
type: kubernetes.io/tls
---
apisix:
  replicaCount: 1
  image:
    repository: api7/api7-ee-3-gateway
    tag: dev
  extraEnvVars:
  - name: API7_GATEWAY_GROUP_SHORT_ID
    value: "tabqbdwnahkqo"
etcd:
  host:
  - "https://12.12.123.123:31344"
  auth:
    tls:
      enabled: true
      existingSecret: name-tls
      certFilename: tls.crt
      certKeyFilename: tls.key
      sni: api7ee3-dp-manager
      verify: true
gateway:
  tls:
    existingCASecret: name-tls
    certCAFilename: ca.crt

Delete gateway instance

IAM Action: gateway:DeleteGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

gateway_instance_id
required
string >= 1

Gateway instance ID.

Responses

Response samples

Content type
application/json
""

Issue a data plane certificate on a gateway group

Issue a client TLS certificate for data plane instances in the specified gateway group to authenticate with the control plane. Use this during gateway bootstrap or certificate rotation.

Required IAM Permission: Action gateway:CreateGatewayInstance, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

Responses

Request samples

Content type
application/json
{
  • "validity_period": 3650
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Create a token for all gateway instances in a gateway group

IAM Action: gateway:CreateGatewayInstance, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
only_token
boolean

If true, the response will only contain the token.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

SSL

Manage SSL/TLS certificates and keys used for HTTPS traffic encryption on gateway groups.

Create an SSL certificate Deprecated

IAM Action: gateway:CreateSSLCertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
One of
name
string [ 1 .. 65536 ] characters

The object name.

desc
string <= 65536 characters

The object description.

snis
Array of strings[ items^\*?[0-9a-zA-Z-._]+$ ]

The SNI list for matching the SSL certificate.

object

Client certificate.

type
string
Value: "server"

Type of certificate. Only support server at the moment, which represents certificates used by the Gateway to verify client requests.

object

Key-value pairs of labels.

required
Private Key Reference (string) or Private Key Content (string)

Private key content or reference to the private key content.

required
Certificate Reference (string) or Certificate Content (string)

Certificate content or reference to the certificate content.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "us-west-rsc",
  • "desc": "Object description.",
  • "snis": [
    ],
  • "client": {
    },
  • "type": "server",
  • "labels": {
    },
  • "key": "$secret://aws/john/apisix-secrets/john-key-auth",
  • "cert": "$secret://aws/john/apisix-secrets/john-key-auth"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all SSL certificates on a gateway group Deprecated

IAM Action: gateway:GetSSLCertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

type
string
Default: "server"
Enum: "client" "server"

Type of certificate. client represents certificates used by the Gateway to access upstream, and server represents certificates used by the Gateway to verify client requests.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get an SSL certificate on a gateway group Deprecated

IAM Action: gateway:GetSSLCertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ssl_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SSL object.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an SSL certificate on a gateway group Deprecated

IAM Action: gateway:UpdateSSLCertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ssl_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SSL object.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
One of
name
string [ 1 .. 65536 ] characters

The object name.

desc
string <= 65536 characters

The object description.

snis
Array of strings[ items^\*?[0-9a-zA-Z-._]+$ ]

The SNI list for matching the SSL certificate.

object

Client certificate.

type
string
Value: "server"

Type of certificate. Only support server at the moment, which represents certificates used by the Gateway to verify client requests.

object

Key-value pairs of labels.

required
Private Key Reference (string) or Private Key Content (string)

Private key content or reference to the private key content.

required
Certificate Reference (string) or Certificate Content (string)

Certificate content or reference to the certificate content.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "us-west-rsc",
  • "desc": "Object description.",
  • "snis": [
    ],
  • "client": {
    },
  • "type": "server",
  • "labels": {
    },
  • "key": "$secret://aws/john/apisix-secrets/john-key-auth",
  • "cert": "$secret://aws/john/apisix-secrets/john-key-auth"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an SSL certificate on a gateway group Deprecated

IAM Action: gateway:DeleteSSLCertificate, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ssl_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SSL object.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Parse an SSL certificate

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
cert
required
string [ 1 .. 65536 ] characters ^[^\$]

The certificate in PEM format.

Responses

Request samples

Content type
application/json
{
  • "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
}

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Validate an SSL certificate and key

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
cert
required
string [ 1 .. 65536 ] characters ^[^\$]

The certificate in PEM format.

key
required
string [ 1 .. 65536 ] characters ^[^\$]

The private key in PEM format.

Responses

Request samples

Content type
application/json
{
  • "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  • "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}

Response samples

Content type
application/json
{
  • "value": true
}

Certificate

Manage TLS client certificates for mutual TLS (mTLS) authentication between gateways and upstream services.

Create a certificate

Create a TLS server certificate for the gateway group, including the certificate chain and private key used for HTTPS termination. Required IAM Permission: Action gateway:CreateCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
string [ 1 .. 65536 ] characters

The object name.

desc
string <= 65536 characters

The object description.

required
Certificate Reference (string) or Certificate Content (string)

Certificate.

object

Key-value pairs of labels.

required
Private Key Reference (string) or Private Key Content (string)

Private key.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "desc": "Object description.",
  • "cert": "$secret://aws/john/apisix-secrets/john-key-auth",
  • "labels": {
    },
  • "key": "$secret://aws/john/apisix-secrets/john-key-auth"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all certificates on a gateway group

List TLS server certificates configured in the gateway group. Use filters such as labels, related SNI, expiration time, and search keywords to find certificates for rotation or troubleshooting. Required IAM Permission: Action gateway:GetCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "exptime"
Enum: "name" "exptime"
search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

sni_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: sni_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The object ID.

sni_name
string

SNI name.

exptime
integer

Filter out results that expired before this time.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a certificate on a gateway group

Retrieve details of a specific TLS server certificate in the gateway group, including its configured metadata and bindings. Required IAM Permission: Action gateway:GetCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the Certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a certificate on a gateway group

Replace the full configuration of an existing TLS server certificate in the gateway group. This operation may impact HTTPS traffic using this certificate. Required IAM Permission: Action gateway:UpdateCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the Certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
string [ 1 .. 65536 ] characters

The object name.

desc
string <= 65536 characters

The object description.

required
Certificate Reference (string) or Certificate Content (string)

Certificate.

object

Key-value pairs of labels.

required
Private Key Reference (string) or Private Key Content (string)

Private key.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "desc": "Object description.",
  • "cert": "$secret://aws/john/apisix-secrets/john-key-auth",
  • "labels": {
    },
  • "key": "$secret://aws/john/apisix-secrets/john-key-auth"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch a certificate on a gateway group

Partially update fields of a TLS server certificate using JSON Patch (RFC 6902). Use this when adjusting selected attributes without replacing the entire certificate object. Required IAM Permission: Action gateway:UpdateCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the Certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a certificate on a gateway group

Delete a TLS server certificate from the gateway group. Ensure no active SNI or route still depends on this certificate before removal. Required IAM Permission: Action gateway:DeleteCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the Certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

CACertificate

Manage Certificate Authority (CA) certificates used to verify client certificates in mTLS authentication.

Create a CA certificate

Create a CA certificate used to verify client certificates during mTLS handshakes in the gateway group. Required IAM Permission: Action gateway:CreateCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
string [ 1 .. 65536 ] characters

The object name.

desc
string <= 65536 characters

The object description.

cert
required
string [ 1 .. 65536 ] characters ^[^\$]

The certificate in PEM format.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "desc": "Object description.",
  • "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all CA certificates on a gateway group

List CA certificates configured for mTLS client certificate verification in the gateway group. Use query filters to locate certificates by labels, expiration, or associated SNI. Required IAM Permission: Action gateway:GetCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "exptime"
Enum: "name" "exptime"
search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

sni_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: sni_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The object ID.

sni_name
string

SNI name.

exptime
integer

Filter out results that expired before this time.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a CA certificate on a gateway group

Retrieve details of a specific CA certificate configured in the gateway group for mTLS validation. Required IAM Permission: Action gateway:GetCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ca_certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a CA certificate on a gateway group

Replace the full configuration of an existing CA certificate used for client certificate verification. Changes can affect mTLS authentication for related traffic. Required IAM Permission: Action gateway:UpdateCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ca_certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
string [ 1 .. 65536 ] characters

The object name.

desc
string <= 65536 characters

The object description.

cert
required
string [ 1 .. 65536 ] characters ^[^\$]

The certificate in PEM format.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "desc": "Object description.",
  • "cert": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch a CA certificate on a gateway group

Partially update a CA certificate with JSON Patch (RFC 6902) operations. Use patching for targeted changes without sending the full CA certificate payload. Required IAM Permission: Action gateway:UpdateCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ca_certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a CA certificate on a gateway group

Delete a CA certificate from the gateway group. Confirm no active mTLS SNI or client verification flow still relies on this certificate. Required IAM Permission: Action gateway:DeleteCertificate, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ca_certificate_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the certificate.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

SNI

Manage Server Name Indication (SNI) mappings that associate domain names with SSL certificates for TLS termination.

Create an SNI

Create an SNI entry that maps one or more hostnames to TLS certificates in the gateway group. This allows a single gateway to serve multiple domains over HTTPS. Required IAM Permission: Action gateway:CreateSNI, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
string [ 1 .. 65536 ] characters

The object name.

domain
string^\*?[0-9a-zA-Z-._]+$

The HTTP host.

desc
string <= 65536 characters

The object description.

Array of Certificate Reference (string) or Certificate Content (string) non-empty

An array of certificates.

object

mTLS configurations.

object

Key-value pairs of labels.

ssl_protocols
Array of strings
Default: ["TLSv1.2","TLSv1.3"]
Items Enum: "TLSv1.1" "TLSv1.2" "TLSv1.3"

An array of TLS protocol versions.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "domain": "httpbin.org",
  • "desc": "Object description.",
  • "certificates": [
    ],
  • "mtls": {
    },
  • "labels": {
    },
  • "ssl_protocols": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all SNIs on a gateway group

List SNI configurations for the gateway group, including hostname and mTLS related settings. Use filters to locate entries by domain, labels, or mTLS enablement. Required IAM Permission: Action gateway:GetSNI, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "name"
Value: "name"
search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

domain
string^\*?[0-9a-zA-Z-._]+$
Example: domain=httpbin.org

The domain of the SNI.

mtls_enabled
Array of booleans

If true, enable mTLS.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get an SNI on a gateway group

Retrieve the configuration of a specific SNI entry in the gateway group, including bound domains and certificate references. Required IAM Permission: Action gateway:GetSNI, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
sni_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SNI object.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an SNI on a gateway group

Replace an existing SNI configuration in full, such as domain mappings, certificate bindings, or mTLS options. Updates take effect on TLS handshakes for matching hostnames. Required IAM Permission: Action gateway:UpdateSNI, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
sni_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SNI object.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
name
string [ 1 .. 65536 ] characters

The object name.

domain
string^\*?[0-9a-zA-Z-._]+$

The HTTP host.

desc
string <= 65536 characters

The object description.

Array of Certificate Reference (string) or Certificate Content (string) non-empty

An array of certificates.

object

mTLS configurations.

object

Key-value pairs of labels.

ssl_protocols
Array of strings
Default: ["TLSv1.2","TLSv1.3"]
Items Enum: "TLSv1.1" "TLSv1.2" "TLSv1.3"

An array of TLS protocol versions.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "domain": "httpbin.org",
  • "desc": "Object description.",
  • "certificates": [
    ],
  • "mtls": {
    },
  • "labels": {
    },
  • "ssl_protocols": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch an SNI on a gateway group

Partially update selected SNI fields using JSON Patch (RFC 6902). This is useful for incremental hostname or certificate adjustments without replacing the entire SNI object. Required IAM Permission: Action gateway:UpdateSNI, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
sni_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SNI object.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an SNI on a gateway group

Delete an SNI entry from the gateway group to remove its hostname-to- certificate mapping. Verify that traffic for those domains has a replacement SNI before deletion. Required IAM Permission: Action gateway:DeleteSNI, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
sni_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the SNI object.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Global Rule

Manage plugins applied to all incoming requests across an entire gateway group, regardless of the matched route.

Create a global rule on a gateway group

Create a global rule that applies plugin configuration to all requests in the gateway group. Use this for cross-cutting behavior such as global authentication, logging, or rate controls. Required IAM Permission: Action gateway:CreateGlobalPluginRule, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
plugins
required
object

Key-value pairs of plugins and their configurations on the object.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all global rules on a gateway group

List global plugin rules configured for the gateway group. This helps audit request-wide policies and understand which plugins are enforced universally. Required IAM Permission: Action gateway:GetGlobalPluginRule, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a global rule on a gateway group

Retrieve one global rule in the gateway group, including its plugin configuration and execution settings. Required IAM Permission: Action gateway:GetGlobalPluginRule, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
global_rule_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the global rule.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a global rule on a gateway group

Replace an existing global rule configuration in full for the gateway group. Changes immediately affect all matching traffic because global rules are applied gateway-wide. Required IAM Permission: Action gateway:UpdateGlobalPluginRule, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
global_rule_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the global rule.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
plugins
required
object

Key-value pairs of plugins and their configurations on the object.

Responses

Request samples

Content type
application/json
{
  • "plugins": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a global rule on a gateway group

Delete a global rule from the gateway group, removing its plugin behavior from all requests. Review related route or service plugin configuration if equivalent controls are still required. Required IAM Permission: Action gateway:DeleteGlobalPluginRule, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
global_rule_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the global rule.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Plugin

Browse available plugins, retrieve their JSON schemas, and view usage details across resources.

Get all plugin schemas and priorities

Authorizations:
APIKeyAuthBasicAuth
query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Type to filter the plugin list. http will only show L7 plugins and stream will only show L4 plugins.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all plugin names

Authorizations:
APIKeyAuthBasicAuth
query Parameters
has_metadata
boolean
Default: false

If true, show plugin names where the plugins have metadata.

subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Type to filter the plugin list. http will only show L7 plugins and stream will only show L4 plugins.

Responses

Response samples

Content type
application/json
[
  • "ip-restriction",
  • "limit-conn",
  • "mqtt-proxy",
  • "prometheus",
  • "syslog"
]

Get schema definition of a plugin

Get schema definition of a plugin, including plugin meta properties and plugin properties. The endpoint returns the same response as the /apisix/admin/schema/plugins/{plugin_name} endpoint when scope is not set.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

query Parameters
scope
string
Value: "all"

The scope of the returned plugin information.
By default, the scope is not set. When set to all, the response includes metadata_schema, priority, version, - and wraps the actual schema under the schema field.

subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Type to filter the plugin list. http will only show L7 plugins and stream will only show L4 plugins.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get schema definition of a plugin

Get schema definition of a plugin, including plugin meta properties and plugin properties.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Type to filter the plugin list. http will only show L7 plugins and stream will only show L4 plugins.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get all plugin details

Authorizations:
APIKeyAuthBasicAuth
query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Type to filter the plugin list. http will only show L7 plugins and stream will only show L4 plugins.

gateway_group_id
string >= 1

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

List all plugin catalogs

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

Get the usage of a plugin in all gateway groups

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Plugin Metadata

Manage shared metadata for plugins that apply globally rather than per-route (e.g., log format configuration shared across all instances of a logging plugin).

List all plugin metadata on a gateway group

List plugin metadata objects configured in the gateway group. Plugin metadata provides shared settings for a plugin type across all its instances. Required IAM Permission: Action gateway:GetPluginMetadata, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a plugin metadata on a gateway group

Retrieve metadata for a specific plugin type in the gateway group. You can optionally request default metadata values for comparison. Required IAM Permission: Action gateway:GetPluginMetadata, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

return_default
boolean
Default: false

When set to true, the default value is returned when plugin metadata is not found.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a plugin metadata on a gateway group

Update the shared metadata configuration for a specific plugin type in the gateway group. The change affects behavior of all plugin instances that consume this metadata. Required IAM Permission: Action gateway:UpdatePluginMetadata, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
object

Plugin metadata.

Responses

Request samples

Content type
application/json
{
  • "disabled_labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a plugin metadata on a gateway group

Delete metadata for a specific plugin type in the gateway group and revert to plugin defaults where applicable. Validate downstream plugin behavior after removal. Required IAM Permission: Action gateway:DeletePluginMetadata, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Get the default value of a plugin metadata

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Custom Plugin

Upload, manage, and deploy custom Lua and WebAssembly (WASM) plugins to extend gateway functionality beyond the built-in plugin set.

List all custom plugins

List all uploaded custom plugins available in the current scope. Use pagination and search parameters to locate plugin packages by name or metadata.

Required IAM Permission: Action gateway:GetCustomPlugin, Resource arn:api7:gateway:gatewaysetting/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
string >= 1

Gateway group ID.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

name
string

Name of the resource.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a custom plugin

Upload and create a new custom plugin package, such as a Lua script plugin or WebAssembly module. After creation, the plugin can be selected in gateway configurations.

Required IAM Permission: Action gateway:CreateCustomPlugin, Resource arn:api7:gateway:gatewaysetting/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
One of
source_code
required
string

The source code for the plugin.

catalog
string

Plugin category, such as "Traffic" or "Observability".

description
string

A brief description of the plugin.

documentation_link
string

Link to the plugin's documentation.

author
string

Author of the plugin.

logo
string

The base64-encoded logo image.

gateway_groups
required
Array of strings[ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

An array of gateway group IDs that the custom plugin is associated with.

Responses

Request samples

Content type
application/json
Example
{
  • "source_code": "local core = require(\"apisix.core\")\nlocal ngx = ngx\n\nlocal schema = {\n type = \"object\"\n}\n\nlocal plugin_name = \"route-id-register\"\n\nlocal _M = {\n version = 0.2,\n priority = 1,\n name = plugin_name,\n schema = schema,\n scope = \"global\",\n}\n\nfunction _M.check_schema(conf)\n return core.schema.check(schema, conf);\nend\n\nfunction _M.log(conf, ctx)\n if ctx.var.route_id then\n ngx.var.route_id = ctx.var.route_id\n end\nend\n\nreturn _M\n",
  • "catalog": "General",
  • "description": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring.",
  • "documentation_link": "https://docs.api7.ai/hub/route-id-register",
  • "author": "plugindev",
  • "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=",
  • "gateway_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a custom plugin

Retrieve metadata and configuration of a specific custom plugin package, including user-uploaded Lua or WASM plugin details.

Required IAM Permission: Action gateway:GetCustomPlugin, Resource arn:api7:gateway:gatewaysetting/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
custom_plugin_id
required
string

Custom plugin ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a custom plugin

Update an existing custom plugin package and its metadata. Changes can affect plugin behavior where the plugin is enabled.

Required IAM Permission: Action gateway:UpdateCustomPlugin, Resource arn:api7:gateway:gatewaysetting/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
custom_plugin_id
required
string

Custom plugin ID.

Request Body schema: application/json
One of
source_code
required
string

The source code for the plugin.

catalog
string

Plugin category, such as "Traffic" or "Observability".

description
string

A brief description of the plugin.

documentation_link
string

Link to the plugin's documentation.

author
string

Author of the plugin.

logo
string

The base64-encoded logo image.

gateway_groups
required
Array of strings[ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

An array of gateway group IDs that the custom plugin is associated with.

Responses

Request samples

Content type
application/json
Example
{
  • "source_code": "local core = require(\"apisix.core\")\nlocal ngx = ngx\n\nlocal schema = {\n type = \"object\"\n}\n\nlocal plugin_name = \"route-id-register\"\n\nlocal _M = {\n version = 0.2,\n priority = 1,\n name = plugin_name,\n schema = schema,\n scope = \"global\",\n}\n\nfunction _M.check_schema(conf)\n return core.schema.check(schema, conf);\nend\n\nfunction _M.log(conf, ctx)\n if ctx.var.route_id then\n ngx.var.route_id = ctx.var.route_id\n end\nend\n\nreturn _M\n",
  • "catalog": "General",
  • "description": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring.",
  • "documentation_link": "https://docs.api7.ai/hub/route-id-register",
  • "author": "plugindev",
  • "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=",
  • "gateway_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a custom plugin

Delete a custom plugin package from the control plane. Ensure the plugin is no longer referenced by services or routes before removal.

Required IAM Permission: Action gateway:DeleteCustomPlugin, Resource arn:api7:gateway:gatewaysetting/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
custom_plugin_id
required
string

Custom plugin ID.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Parse custom plugin code

Parse and validate custom plugin source payload to extract plugin metadata and detect structural issues before creating or updating a plugin.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
file
required
string

Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.

Responses

Request samples

Content type
application/json
{
  • "file": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo="
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Secret Provider

Manage integrations with external secret managers (HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets) used to store sensitive plugin configuration.

List all secret providers on a gateway group

List secret provider integrations configured for the gateway group, such as Vault or cloud secret managers. Use this view to audit external secret backends available for plugin and route configurations. Required IAM Permission: Action gateway:GetSecretProvider, Resource arn:api7:gateway:gatewaygroup/%s/secret_provider/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a secret provider on a gateway group

Retrieve details of one secret provider integration in the gateway group, including provider-specific connection settings. Required IAM Permission: Action gateway:GetSecretProvider, Resource arn:api7:gateway:gatewaygroup/%s/secret_provider/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
secret_provider
required
string
Enum: "vault" "aws" "kubernetes"

Secret provider.

secret_provider_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Secret provider ID.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a secret provider on a gateway group

Delete a secret provider integration from the gateway group. Ensure no plugin or resource still references secrets from this provider before removal. Required IAM Permission: Action gateway:DeleteSecretProvider, Resource arn:api7:gateway:gatewaygroup/%s/secret_provider/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
secret_provider
required
string
Enum: "vault" "aws" "kubernetes"

Secret provider.

secret_provider_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Secret provider ID.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
""

Update a secret provider on a gateway group

Create or replace the configuration of a secret provider integration in the gateway group. This controls how the gateway resolves externally managed secrets referenced by runtime configs. Required IAM Permission: Action gateway:PutSecretProvider, Resource arn:api7:gateway:gatewaygroup/%s/secret_provider/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
secret_provider
required
string
Enum: "vault" "aws" "kubernetes"

Secret provider.

secret_provider_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Secret provider ID.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
One of
uri
required
string^[^/]+://([\da-zA-Z.-]+|\[[\da-fA-F:]+\])(:\d...

Vault endpoint.

prefix
required
string

Vault prefix to access secrets.

token
required
string

Vault token.

namespace
string

Vault namespace.

kv_version
string
Default: "kv-v1"
Value: "kv-v1"

Vault KV secrets engine version.

authentication_method
string
Default: "token"
Value: "token"

Authentication method.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
Example
{
  • "uri": "http://10.42.17.8:8200",
  • "prefix": "kv/apisix",
  • "token": "apisix-quickstart-vault-token",
  • "namespace": "apisix",
  • "kv_version": "kv-v1",
  • "authentication_method": "token",
  • "desc": "Object description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Proto

Manage Protocol Buffer (protobuf) definitions used by the gRPC transcoding plugin to convert between HTTP/JSON and gRPC.

List all protos on a gateway group

List Protocol Buffers definitions stored in the gateway group. These proto files are used by gRPC-transcode related configurations to map REST calls to gRPC methods. Required IAM Permission: Action gateway:GetProto, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a proto on a gateway group

Upload a new .proto definition to the gateway group for gRPC transcoding scenarios. Ensure package and service definitions align with upstream gRPC services. Required IAM Permission: Action gateway:CreateProto, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
content
required
string [ 1 .. 1048576 ] characters

The protobuf content.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "content": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a proto on a gateway group

Retrieve one proto definition from the gateway group, including its current content and metadata. Required IAM Permission: Action gateway:GetProto, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
proto_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the proto.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a proto on a gateway group

Replace an existing proto definition in the gateway group. After updates, verify dependent gRPC-transcode routes still match the revised service and method signatures. Required IAM Permission: Action gateway:UpdateProto, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
proto_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the proto.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Request Body schema: application/json
content
required
string [ 1 .. 1048576 ] characters

The protobuf content.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "content": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a proto on a gateway group

Delete a proto definition from the gateway group. Check for any gRPC-transcode plugin configurations that still reference this proto before deletion. Required IAM Permission: Action gateway:DeleteProto, Resource arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
proto_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the proto.

query Parameters
gateway_group_id
required
string >= 1
Example: gateway_group_id=86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID. Optional when using the gateway group admin key to authenticate.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Service Registry

Manage connections to external service registries (Kubernetes, Nacos, Consul) for automatic upstream service discovery.

List all service registry connections on a gateway group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "last_connect_time"

Index to order service registry connections by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a service registry connection on a gateway group

IAM Action: gateway:ConnectServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
One of
name
string [ 1 .. 100 ] characters

The object name.

description
string

Service registry description.

object

Health check configurations.

type
required
string
Value: "kubernetes"

The kubernetes service type.

required
object

Kubernetes service registry configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "sample-service-registry",
  • "description": "service registry description",
  • "health_check": {
    },
  • "type": "kubernetes",
  • "kubernetes_config": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a service registry connection on a gateway group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a service registry connection on a gateway group

IAM Action: gateway:UpdateServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
required
One of
name
string [ 1 .. 100 ] characters

The object name.

description
string

Service registry description.

object

Health check configurations.

type
required
string
Value: "kubernetes"

The kubernetes service type.

required
object

Kubernetes service registry configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "sample-service-registry",
  • "description": "service registry description",
  • "health_check": {
    },
  • "type": "kubernetes",
  • "kubernetes_config": {
    }
}

Response samples

Content type
application/json
{
  • "value": { }
}

Delete a service registry connection on a gateway group

IAM Action: gateway:DisconnectServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
""

List all published services connected to a service registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "publish_time" "name"

Index to order published services by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List all internal services in a Kubernetes service registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all namespaces in a Nacos service registry

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List all groups in a Nacos namespace

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

nacos_namespace
required
string >= 1
Example: public

Nacos namespace name.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 5
}

List all internal services in a Nacos group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

nacos_namespace
required
string >= 1
Example: public

Nacos namespace name.

nacos_group
required
string >= 1
Example: DEFAULT_GROUP

Nacos group.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 5
}

Get all instance metadata of a Nacos services registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

nacos_namespace
required
string >= 1
Example: public

Nacos namespace name.

nacos_group
required
string >= 1
Example: DEFAULT_GROUP

Nacos group.

nacos_service
required
string >= 1
Example: api7ee3-keycloak

Nacos service.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 3,
  • "value": {
    }
}

List all datacenters in a Consul service registry

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 2
}

List all services in a Consul datacenter

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

consul_datacenter
required
string >= 1
Example: dc1

Consul datacenter name.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 3
}

Get all instance metadata of a Consul service

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

consul_datacenter
required
string >= 1
Example: dc1

Consul datacenter name.

consul_service
required
string >= 1
Example: web

Consul service name.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get health check history of a service registry connection on a gateway group

IAM Action: gateway:GetServiceRegistry, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
service_registry_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Service registry ID.

gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "connect_time"
Value: "connect_time"

Index to order health check history by.

status
Array of strings
Items Enum: "healthy" "lost_connection" "connecting"

Service registry connection status.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

User

Manage dashboard user accounts, including invitations, profile updates, password management, and authentication (login/logout via OIDC, SAML, LDAP, or built-in credentials).

List all users

List dashboard user accounts with pagination and role-based filtering. Use this to audit who can authenticate by local credentials or configured SSO methods. Required IAM Permission: Action iam:GetUser, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

roles
Array of strings >= 1

Any array of roles.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a user

Get one dashboard user account by ID to inspect account details and current state. Required IAM Permission: Action iam:GetUser, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
user_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

The user ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update basic attributes of a user

Update basic attributes of a specified dashboard user account. This is intended for administrative account maintenance. Required IAM Permission: Action iam:UpdateUser, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
user_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

The user ID.

Request Body schema: application/json
required
object

Key-value pairs of labels.

property name*
additional property
string [ 1 .. 65536 ] characters ^.+$

Responses

Request samples

Content type
application/json
{
  • "labels": {
    }
}

Response samples

Content type
application/json
""

Delete a user

Delete a dashboard user account and revoke its login access. Verify downstream ownership and role dependencies before removal. Required IAM Permission: Action iam:DeleteUser, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
user_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

The user ID.

Responses

Response samples

Content type
application/json
""

Update the user's permission boundaries

Replace a user's permission boundaries using permission policy IDs. Boundaries constrain the maximum effective permissions a user can obtain. Required IAM Permission: Action iam:UpdateUserBoundary, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
user_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

The user ID.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "efd3bcc7-b61a-47ec-942b-b36bf249f1da"
]

Response samples

Content type
application/json
""

Reset the password to specific value

Reset a specified user's password to an administrator-provided value. Use this for recovery or emergency credential rotation. Required IAM Permission: Action iam:ResetPassword, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
user_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

The user ID.

Request Body schema: application/json
required
password
required
string [ 1 .. 128 ] characters

The password of the user.

Responses

Request samples

Content type
application/json
{
  • "password": "safe-password"
}

Response samples

Content type
application/json
""

Get my user detail

Get details of the currently authenticated dashboard user.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update my user profile

Update profile attributes of the currently authenticated dashboard user without changing role assignments.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
""

Update the user email

Update the email address for the currently authenticated user account.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
email
required
string <email> [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
""

Delete the user email

Remove the email address currently bound to the authenticated user account.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
""

Invite a user

Invite a new dashboard user account. The invitation initiates onboarding so the user can later sign in with supported authentication methods. Required IAM Permission: Action iam:InviteUser, Resource arn:api7:iam:user/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
username
required
string [ 1 .. 128 ] characters

The username of the user.

password
required
string [ 1 .. 128 ] characters

The password of the user.

boundaries
Array of strings

The permission boundaries of the user.

name
string [ 1 .. 128 ] characters

The name of the user.

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "safe-password",
  • "boundaries": [
    ],
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update my user password

Change the password for the currently authenticated user account.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
old_password
string [ 1 .. 128 ] characters
new_password
required
string [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "old_password": "old-password",
  • "new_password": "new-password"
}

Response samples

Content type
application/json
""

Log in to API7 Enterprise using the built-in username and password

Authenticate a dashboard user with built-in username and password credentials and create a session.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
username
required
string [ 1 .. 128 ] characters

The username of the user.

password
required
string [ 1 .. 128 ] characters

The password of the user.

Responses

Request samples

Content type
application/json
{
  • "username": "john",
  • "password": "safe-password"
}

Response samples

Content type
application/json
{
  • "value": { }
}

Log out from API7 Enterprise using the built-in username and password

Log out the current built-in authentication session and invalidate related session state.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Update assigned roles for a user

Update role assignments for a user. Assigned roles determine the permission policies and effective access granted to that account. Required IAM Permission: Action iam:UpdateUserRole, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
user_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

The user ID.

Request Body schema: application/json
required
roles
required
Array of strings[ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

An array of role IDs associated with a user.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ]
}

Response samples

Content type
application/json
""

Check if a user has permissions on specific resources

Evaluate whether a user is allowed to perform specified actions on given resources based on current RBAC and policy configuration.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
additional property
object (properties)
resource
required
string

An ARN-style identifier that specifies one or multiple resources.

action
required
string

A specific permission that defines what operation can be performed on the resource.

Context for Gateway Group (object) or Context for Service (object) or Context for Published Service (object) or Context for Role (object) or Context for Permission Policy (object) or Context for User (object) or Context for Consumer (object) or Context for Secret (object) or Context for Contact Point (object) or Context for Alert Policy (object) or Context for Developer (object) or Context for API Product (object) or Context for CA Certificate (object) or Context for Certificate (object) or Context for SNI (object) or Context for Portal (object)

Additional conditions or labels used to further narrow down which resources the action applies to, in combination with the resource definition.

Responses

Request samples

Content type
application/json
{
  • "hasAccess": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Log in to API7 Enterprise using the LDAP username and password

Authenticate a user through the specified LDAP login option and create a dashboard session.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Request Body schema: application/json
username
required
string [ 1 .. 128 ] characters

The username of the user.

password
required
string [ 1 .. 128 ] characters

The password of the user.

Responses

Request samples

Content type
application/json
{
  • "username": "john",
  • "password": "safe-password"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Log out from API7 Enterprise using the LDAP username and password

Log out a session established via LDAP authentication for the specified login option.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Log in using the CAS provider

Start or complete CAS login for the selected login option, including CAS ticket processing.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

query Parameters
ticket
string

The field of the CAS protocol.

Responses

Log out using the CAS provider

Start CAS logout for the selected login option and redirect to the configured post-logout target.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

query Parameters
redirect
required
string

Redirect to the given URL after logout.

Responses

Log in using the OIDC provider

Start OIDC authentication by redirecting to the configured OpenID Connect provider for the selected login option.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Responses

Log in using the OIDC provider

Process OIDC callback parameters and complete authentication for the selected login option.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

query Parameters
state
required
string

The field of the OIDC protocol.

code
required
string

The field of the OIDC protocol.

Responses

Log out using the OIDC provider

Start OIDC logout flow and redirect through the provider logout endpoint for the selected login option.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Responses

SAML login (redirect to IdP and call back to Dashboard)

Start SAML 2.0 login by redirecting to the identity provider and preparing for ACS callback handling.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

query Parameters
redirect_uri
string non-empty ^/

Path to be redirected after callback.

Responses

SAML Logout (redirect to IdP and call back to Dashboard)

Start SAML 2.0 logout by redirecting through the identity provider for the selected login option.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

query Parameters
redirect_uri
string non-empty ^/

Path to be redirected after callback.

Responses

SAML ACS/SLO callback (from IdP to Dashboard)

Handle SAML ACS/SLO callback payloads posted by the identity provider for the selected login option.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Request Body schema: application/x-www-form-urlencoded
SAMLResponse
required
string

Base64 encoded SAML response

RelayState
string

State information to be relayed with the response

Responses

SAML ACS/SLO callback (from IdP to Dashboard)

Handle SAML ACS/SLO callback query parameters from the identity provider and finalize SAML sign-in or sign-out.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

query Parameters
SAMLResponse
required
string

Base64 encoded SAML response.

RelayState
string

State information to be relayed with the response.

Responses

SAML ACS/SLO callback (from IdP to Dashboard)

Handle SAML ACS/SLO callback payloads posted by the identity provider for the selected login option.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Request Body schema: application/x-www-form-urlencoded
SAMLResponse
required
string

Base64 encoded SAML response

RelayState
string

State information to be relayed with the response

Responses

SAML SP metadata

Get SAML service provider metadata XML for the specified login option to help configure identity-provider trust.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Responses

Role

Manage RBAC roles that group permissions and can be assigned to users to control access to dashboard resources.

Update assigned roles for a user

Update role assignments for a user. Assigned roles determine the permission policies and effective access granted to that account. Required IAM Permission: Action iam:UpdateUserRole, Resource arn:api7:iam:user/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
user_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

The user ID.

Request Body schema: application/json
required
roles
required
Array of strings[ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

An array of role IDs associated with a user.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ]
}

Response samples

Content type
application/json
""

List all roles

List RBAC roles with pagination and filtering. Results include built-in roles (Super Admin, Admin, Viewer) and custom roles. Required IAM Permission: Action iam:GetRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a role

Create a custom RBAC role used to group permission policies. The new role can then be assigned to users. Required IAM Permission: Action iam:CreateRole, Resource arn:api7:iam:role/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 256 ] characters

The role name.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

policies
Array of strings non-empty unique [ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

The polices attached to the role.

Responses

Request samples

Content type
application/json
{
  • "name": "View Consumer",
  • "desc": "This role allows users to view comsumers.",
  • "labels": {
    },
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a role

Get detailed information for a specific RBAC role. This includes role metadata used to grant permissions through user-role assignments. Required IAM Permission: Action iam:GetRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a role

Update a role definition by ID. Changes affect all users currently assigned to the role. Required IAM Permission: Action iam:UpdateRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

Request Body schema: application/json
required
name
required
string [ 1 .. 256 ] characters

The role name.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

policies
Array of strings non-empty unique [ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]

The polices attached to the role.

Responses

Request samples

Content type
application/json
{
  • "name": "View Consumer",
  • "desc": "This role allows users to view comsumers.",
  • "labels": {
    },
  • "policies": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a role

Delete a custom RBAC role from the organization. Review user assignments first to avoid unintended access loss. Required IAM Permission: Action iam:DeleteRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

List all permission policies attached to a role

List permission policies attached to a role. This reveals the policy statements that determine the role's effective access. Required IAM Permission: Action iam:GetPermissionPolicy, Resource arn:api7:iam:permissionpolicy/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Attach permission policies to a role

Attach permission policies to a role. Attached policies immediately affect all users assigned to that role. Required IAM Permission: Action iam:UpdateRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "efd3bcc7-b61a-47ec-942b-b36bf249f1da"
]

Response samples

Content type
application/json
{
  • "value": { }
}

Detach permission policies of a role

Detach permission policies from a role. Removing policies may reduce or revoke access for assigned users. Required IAM Permission: Action iam:UpdateRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "efd3bcc7-b61a-47ec-942b-b36bf249f1da"
]

Response samples

Content type
application/json
{
  • "value": { }
}

Check if a user has permissions on specific resources

Evaluate whether a user is allowed to perform specified actions on given resources based on current RBAC and policy configuration.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
additional property
object (properties)
resource
required
string

An ARN-style identifier that specifies one or multiple resources.

action
required
string

A specific permission that defines what operation can be performed on the resource.

Context for Gateway Group (object) or Context for Service (object) or Context for Published Service (object) or Context for Role (object) or Context for Permission Policy (object) or Context for User (object) or Context for Consumer (object) or Context for Secret (object) or Context for Contact Point (object) or Context for Alert Policy (object) or Context for Developer (object) or Context for API Product (object) or Context for CA Certificate (object) or Context for Certificate (object) or Context for SNI (object) or Context for Portal (object)

Additional conditions or labels used to further narrow down which resources the action applies to, in combination with the resource definition.

Responses

Request samples

Content type
application/json
{
  • "hasAccess": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Permission Policy

Define fine-grained IAM permission policies specifying which actions are allowed or denied on specific resource types.

List all permission policies attached to a role

List permission policies attached to a role. This reveals the policy statements that determine the role's effective access. Required IAM Permission: Action iam:GetPermissionPolicy, Resource arn:api7:iam:permissionpolicy/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Attach permission policies to a role

Attach permission policies to a role. Attached policies immediately affect all users assigned to that role. Required IAM Permission: Action iam:UpdateRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "efd3bcc7-b61a-47ec-942b-b36bf249f1da"
]

Response samples

Content type
application/json
{
  • "value": { }
}

Detach permission policies of a role

Detach permission policies from a role. Removing policies may reduce or revoke access for assigned users. Required IAM Permission: Action iam:UpdateRole, Resource arn:api7:iam:role/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
role_id
required
string >= 1
Example: 4b9b56d1-147e-49ef-bcaa-88cc5bcf403f

Role ID.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "efd3bcc7-b61a-47ec-942b-b36bf249f1da"
]

Response samples

Content type
application/json
{
  • "value": { }
}

Create a permission policy

Create a fine-grained permission policy with allow/deny statements over specific IAM actions and resource ARNs. Required IAM Permission: Action iam:CreatePermissionPolicy, Resource arn:api7:iam:permissionpolicy/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

The policy name.

type
string
Enum: "built_in" "custom"

The permission policy type.

desc
string <= 65536 characters

The description of the policy.

object

The labels of the policy.

required
object

Policy document.

Responses

Request samples

Content type
application/json
{
  • "name": "sample-policy",
  • "type": "built_in",
  • "desc": "Object description.",
  • "labels": {
    },
  • "policy_document": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all permission policies

List available permission policies in the organization with pagination and filters. Use this to choose policies for roles and boundaries. Required IAM Permission: Action iam:GetPermissionPolicy, Resource arn:api7:iam:permissionpolicy/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get the permission policy authoring catalog

Return the static catalog used by the console Visual Editor to author permission policies: every supported resource type with its ARN templates, available list endpoint, condition keys, and the ordered list of actions classified by access level. The payload is purely configuration data, depends on no database state and is safe for any authenticated user to read.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a permission policy

Get a permission policy by ID, including all statements and metadata. Required IAM Permission: Action iam:GetPermissionPolicy, Resource arn:api7:iam:permissionpolicy/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
permission_policy_id
required
string >= 1

Permission policy ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a permission policy

Update an existing permission policy definition. Changes apply to all roles or users that reference this policy. Required IAM Permission: Action iam:UpdatePermissionPolicy, Resource arn:api7:iam:permissionpolicy/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
permission_policy_id
required
string >= 1

Permission policy ID.

Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

The policy name.

type
string
Enum: "built_in" "custom"

The permission policy type.

desc
string <= 65536 characters

The description of the policy.

object

The labels of the policy.

required
object

Policy document.

Responses

Request samples

Content type
application/json
{
  • "name": "sample-policy",
  • "type": "built_in",
  • "desc": "Object description.",
  • "labels": {
    },
  • "policy_document": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a permission policy

Delete a permission policy. Ensure references are reviewed first to prevent accidental permission breakage. Required IAM Permission: Action iam:DeletePermissionPolicy, Resource arn:api7:iam:permissionpolicy/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
permission_policy_id
required
string >= 1

Permission policy ID.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

List the Roles or Users that directly reference the Permission Policy

List roles and users that directly reference the specified permission policy. This helps estimate impact before policy changes. Required IAM Permission: Action iam:GetPermissionPolicy, Resource arn:api7:iam:permissionpolicy/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
permission_policy_id
required
string >= 1

Permission policy ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Token

Manage API access tokens (API keys) for programmatic authentication with the dashboard APIs.

Create a token

Create a new API access token for programmatic, non-interactive access to dashboard APIs. You can configure token metadata and optional expiration at creation time.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
name
required
string <= 40 characters

The token name.

expires_at
required
integer <int32>

The expiration timestamp of the token. 0 means the token will not expire.

Responses

Request samples

Content type
application/json
{
  • "name": "test-token",
  • "expires_at": 1752288235
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all tokens

List API access tokens created for programmatic dashboard API access, with pagination, ordering, and search filters.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
order_by
string
Default: "created_at"
Enum: "created_at" "updated_at" "expires_at"

Index to order the tokens by.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a token

Get details of an API access token by token ID.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the token.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a token

Update mutable properties of an API access token, such as expiration and metadata fields.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the token.

Request Body schema: application/json
name
required
string <= 40 characters

The token name.

Responses

Request samples

Content type
application/json
{
  • "name": "test-token"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a token

Delete an API access token and immediately revoke its ability to authenticate API requests.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the token.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Regenerate a token

Regenerate the secret value of an existing API access token. Clients must replace stored credentials after regeneration.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the token.

Request Body schema: application/json
expires_at
required
integer <int32>

The expiration timestamp of the token. 0 means the token will not expire.

Responses

Request samples

Content type
application/json
{
  • "expires_at": 1752288235
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Dashboard Login Option

Configure authentication providers (OIDC, SAML, LDAP, built-in) available on the dashboard and developer portal login pages.

Get a login option

Get a login option configuration by ID. This returns settings for one external authentication integration such as OIDC, LDAP, SAML 2.0, or CAS. Required IAM Permission: Action iam:GetLoginOption, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a login option

Fully update a login option configuration with a complete protocol-specific payload. Required IAM Permission: Action iam:UpdateLoginOption, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Request Body schema: application/json
One of
name
string [ 1 .. 256 ] characters

Name of the login option.

logo
string

The base64-encoded logo image.

disable
boolean
Default: false

If true, disable the login option.

Array of objects

A list of role mappings defining operations and conditions under which roles are applied.

Array of objects

A list of permission boundary mappings defining operations and conditions under which permission boundary are applied.

provider_type
string
Value: "oidc"

The login option type.

object

OIDC configuration.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-login",
  • "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=",
  • "disable": false,
  • "role_mapping": [
    ],
  • "boundary_mapping": [
    ],
  • "provider_type": "oidc",
  • "oidc_config": {}
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch a login option

Partially update a login option using JSON Patch (RFC 6902). Use this for targeted changes without replacing full configuration. Required IAM Permission: Action iam:UpdateLoginOption, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a login option

Delete a login option and remove that authentication method from available sign-in choices. Required IAM Permission: Action iam:DeleteLoginOption, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
login_option_id
required
string

Login option ID.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

List all login options

List all configured login options for the organization, including protocol-specific provider settings. Required IAM Permission: Action iam:GetLoginOption, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

name
string

Name of the resource.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a login option

Create a new login option for external authentication integration. Supported protocols include OIDC, LDAP, SAML 2.0, and CAS. Required IAM Permission: Action iam:CreateLoginOption, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
One of
name
string [ 1 .. 256 ] characters

Name of the login option.

logo
string

The base64-encoded logo image.

disable
boolean
Default: false

If true, disable the login option.

Array of objects

A list of role mappings defining operations and conditions under which roles are applied.

Array of objects

A list of permission boundary mappings defining operations and conditions under which permission boundary are applied.

provider_type
string
Value: "oidc"

The login option type.

object

OIDC configuration.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-login",
  • "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=",
  • "disable": false,
  • "role_mapping": [
    ],
  • "boundary_mapping": [
    ],
  • "provider_type": "oidc",
  • "oidc_config": {}
}

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List all login options (public)

List login options. No authentication is required, and provider or policy/role details are not included in the response.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

name
string

Name of the resource.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

License

View and import the API7 Enterprise license that governs feature availability and usage limits.

Get API7 Enterprise license details

Retrieve current API7 Enterprise license information, including validity and licensed capabilities. Use this endpoint to inspect license status for operations and troubleshooting.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Import or update the API7 Enterprise license

Import a new license payload or update the existing enterprise license for the organization. You can optionally use dry-run mode to validate license content before applying it.

Required IAM Permission: Action iam:UpdateLicense, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
dry-run
string
Value: "all"

When specified, run the operation in dry-run mode.

Request Body schema: application/json
required
data
required
string

Encoded license data.

Responses

Request samples

Content type
application/json
{
  • "data": "“xxxx1N-tNaTpttX-NjOdXjyg\""
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Label

Retrieve all labels (key-value pairs) currently applied across resources for filtering and organization.

Get all labels of a resource type

List available key-value labels for the specified resource type. Use these labels to organize resources and apply label-based filtering in list queries.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
resource_type
required
string
Enum: "gateway_group" "consumer" "consumer_credential" "ssl" "service" "route" "stream_route" "role" "permission_policy" "published_service" "secret" "contact_point" "alert_policy" "certificate" "api_product" "sni" "portal" "dcr_provider"

Resource type.

query Parameters
gateway_group_id
string >= 1

Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Alert

Manage alert policies that monitor API metrics and trigger notifications when configurable thresholds are breached.

List all alert policies

List alert policies configured for monitoring conditions such as error rates, latency thresholds, and availability checks. Use query filters to narrow results by severity, status, labels, and search terms.

Required IAM Permission: Action gateway:GetAlertPolicy, Resource arn:api7:gateway:alert/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at" "name" "severity"

Index to order alert policies by.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

status
Array of strings
Items Enum: "enabled" "disabled"

Alert enablement status.

severity
Array of strings
Items Enum: "high" "medium" "low"

Alert severity.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create an alert policy

Create a new alert policy that defines trigger conditions, evaluation behavior, and notification routing. After creation, the policy can begin generating alert history entries when conditions are met.

Required IAM Permission: Action gateway:CreateAlertPolicy, Resource arn:api7:gateway:alert/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

The alert policy name.

desc
string <= 65536 characters

The alert policy description.

object

Key-value pairs of labels.

enable
boolean
Default: true

If true, enable the alert policy.

check_interval
integer [ 1 .. 86400 ]

The check interval for the alert policy. The unit is second.

severity
string
Default: "medium"
Enum: "high" "medium" "low"

The alert severity level.

trigger_logical_operator
required
string
Default: "All"
Enum: "All" "Any"

The logical relationship between multiple triggers.

required
Array of Status Code (object) or Certificate Expiry (object) or License Expiry (object) or Gateway Instance Offline (object) or Data Plane Cores Exceeded (object) or Numbers of Healthy Gateway Instances (object) or Shared Dict Free Space Bytes (object) or Shared Dict Free Space Percentage (object) non-empty

The alert trigger conditions.

Array of Email (object) or Webhook (object)

The alert notifications.

Array of objects

Debug session configurations to create automatically when the alert is triggered.

Responses

Request samples

Content type
application/json
{
  • "name": "500 status alert",
  • "desc": "Object description.",
  • "labels": {
    },
  • "enable": true,
  • "check_interval": 1,
  • "severity": "high",
  • "trigger_logical_operator": "All",
  • "trigger_conditions": [
    ],
  • "notifications": [
    ],
  • "debug_sessions": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get an alert policy

Retrieve the full configuration of a specific alert policy, including its trigger rules and notification settings. Use this endpoint before updating or troubleshooting policy behavior.

Required IAM Permission: Action gateway:GetAlertPolicy, Resource arn:api7:gateway:alert/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
alert_policy_id
required
string

Alert policy ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an alert policy

Delete an existing alert policy so it no longer evaluates conditions or sends notifications. This action affects future alerting only and does not remove historical alert records.

Required IAM Permission: Action gateway:DeleteAlertPolicy, Resource arn:api7:gateway:alert/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
alert_policy_id
required
string

Alert policy ID.

Responses

Response samples

Content type
application/json
""

Update an alert policy

Replace the full configuration of an alert policy with the provided payload. Use this operation when you want to update all policy fields in a single request.

Required IAM Permission: Action gateway:UpdateAlertPolicy, Resource arn:api7:gateway:alert/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
alert_policy_id
required
string

Alert policy ID.

Request Body schema: application/json
name
required
string [ 1 .. 100 ] characters

The alert policy name.

desc
string <= 65536 characters

The alert policy description.

object

Key-value pairs of labels.

enable
boolean
Default: true

If true, enable the alert policy.

check_interval
integer [ 1 .. 86400 ]

The check interval for the alert policy. The unit is second.

severity
string
Default: "medium"
Enum: "high" "medium" "low"

The alert severity level.

trigger_logical_operator
required
string
Default: "All"
Enum: "All" "Any"

The logical relationship between multiple triggers.

required
Array of Status Code (object) or Certificate Expiry (object) or License Expiry (object) or Gateway Instance Offline (object) or Data Plane Cores Exceeded (object) or Numbers of Healthy Gateway Instances (object) or Shared Dict Free Space Bytes (object) or Shared Dict Free Space Percentage (object) non-empty

The alert trigger conditions.

Array of Email (object) or Webhook (object)

The alert notifications.

Array of objects

Debug session configurations to create automatically when the alert is triggered.

Responses

Request samples

Content type
application/json
{
  • "name": "500 status alert",
  • "desc": "Object description.",
  • "labels": {
    },
  • "enable": true,
  • "check_interval": 1,
  • "severity": "high",
  • "trigger_logical_operator": "All",
  • "trigger_conditions": [
    ],
  • "notifications": [
    ],
  • "debug_sessions": [
    ]
}

Response samples

Content type
application/json
{
  • "value": { }
}

Patch an alert policy

Partially update an alert policy using JSON Patch (RFC 6902) operations. This is useful for targeted edits without resubmitting the full policy definition.

Required IAM Permission: Action gateway:UpdateAlertPolicy, Resource arn:api7:gateway:alert/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
alert_policy_id
required
string

Alert policy ID.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": { }
}

List all alert histories

List historical alert events triggered by alert policies, including occurrence time, severity, and related gateway group context. Use time-range and policy filters to investigate incidents and alert trends.

Required IAM Permission: Action gateway:GetAlertPolicy, Resource arn:api7:gateway:alert/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
alert_policy_id
string

Alert policy ID.

severity
Array of strings
Items Enum: "high" "medium" "low"

Alert severity.

start_at
integer

Start at timestamp to filter the audit logs.

end_at
integer

End at timestamp to filter the audit logs.

gateway_group_id
string >= 1

Gateway group ID.

order_by
string
Default: "alert_time"
Value: "alert_time"

Index to order alerts by.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Contact Point

Manage notification channels (Webhook, Slack, email, etc.) used to deliver alert notifications.

Create a contact point

Create a new contact point to deliver alert notifications through channels such as email, webhook, Slack, or DingTalk. The created contact point can then be referenced by alert policies.

Required IAM Permission: Action iam:CreateContactPoint, Resource arn:api7:iam:contactpoint/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
One of
name
string [ 1 .. 256 ] characters

Name of the contact point.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

type
string
Value: "email"

Type of contact point.

required
object

Contact point email configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "cp-docs-test",
  • "desc": "Object description.",
  • "labels": {
    },
  • "type": "email",
  • "email_config": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List Contact Points

List contact points available for alert notification delivery. Use filters and pagination to locate channels by type, labels, or search terms.

Required IAM Permission: Action iam:GetContactPoint, Resource arn:api7:iam:contactpoint/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
type
string
Enum: "email" "webhook"
labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

search
string
Example: search=version%3Dv2

Condition to search resources by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a contact point

Retrieve details of a specific contact point, including its configuration and metadata. Use this before updating or validating notification settings.

Required IAM Permission: Action iam:GetContactPoint, Resource arn:api7:iam:contactpoint/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
contact_point_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Contact point ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a contact point

Update a contact point configuration, such as destination address, authentication details, or labels. Changes take effect for subsequent alert notifications.

Required IAM Permission: Action iam:UpdateContactPoint, Resource arn:api7:iam:contactpoint/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
contact_point_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Contact point ID.

Request Body schema: application/json
One of
name
string [ 1 .. 256 ] characters

Name of the contact point.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

type
string
Value: "email"

Type of contact point.

required
object

Contact point email configurations.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "cp-docs-test",
  • "desc": "Object description.",
  • "labels": {
    },
  • "type": "email",
  • "email_config": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a contact point

Delete a contact point so it can no longer be used as an alert notification channel. Ensure dependent alert policies are updated to avoid delivery failures.

Required IAM Permission: Action iam:DeleteContactPoint, Resource arn:api7:iam:contactpoint/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
contact_point_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Contact point ID.

Responses

Response samples

Content type
application/json
""

List notification logs of a contact point

List notification delivery logs for a contact point, including status, target resource type, and timestamps. Use this to troubleshoot failed or delayed alert notifications.

Required IAM Permission: Action iam:GetContactPoint, Resource arn:api7:iam:contactpoint/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
contact_point_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Contact point ID.

query Parameters
start_at
integer

Start at timestamp to filter the audit logs.

end_at
integer

End at timestamp to filter the audit logs.

resource_type
string
Enum: "alert_policy" "api_product_notification"

Type of notification.

status
string
Enum: "success" "failed"

Notification sending status.

order_by
string
Default: "send_time"
Value: "send_time"

Index to order the notifications by.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List a contact point usages

List resources that currently reference the specified contact point. Check usage before deletion or major edits to understand downstream impact.

Required IAM Permission: Action iam:GetContactPoint, Resource arn:api7:iam:contactpoint/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
contact_point_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Contact point ID.

query Parameters
resource_type
string
Enum: "alert_policy" "api_product_notification"

Type of notification.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Audit Logs

Query and export audit log entries that record every administrative action performed on the dashboard.

List all audit logs

Retrieve immutable audit log records for administrative and configuration actions, including who performed each action and when. Use filters such as event type, operator, resource, gateway group, and time range to narrow the result set.

Required IAM Permission: Action iam:GetAudit, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
event_type
string
Example: event_type=AddConsumerCredential

The event type. Event types can be looked up using the /api/audit_logs/event_types endpoint.

operator_id
string

The user ID of the operator.

gateway_group_id
string >= 1

Gateway group ID.

resource_id
string

The resource ID.

start_at
integer

Start at timestamp to filter the audit logs.

end_at
integer

End at timestamp to filter the audit logs.

order_by
string
Default: "event_time"
Value: "event_time"

Index to order audit logs by.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

List all event types of audit logs

List supported audit event types that can be used for filtering and analysis when querying audit logs.

No IAM permission required.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Export all audit logs

Export audit logs that match the specified filters into a downloadable file format for compliance, archival, or external analysis. Apply event, operator, resource, and time-range filters before export to control data scope.

Required IAM Permission: Action iam:ExportAudits, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
event_type
string
Example: event_type=AddConsumerCredential

The event type. Event types can be looked up using the /api/audit_logs/event_types endpoint.

operator_id
string

The user ID of the operator.

gateway_group_id
string >= 1

Gateway group ID.

resource_id
string

The resource ID.

start_at
integer

Start at timestamp to filter the audit logs.

end_at
integer

End at timestamp to filter the audit logs.

format
required
string
Enum: "json" "csv"

Format to export.

Responses

Audit Config

Configure audit logging behavior, such as retention period and which events to record.

Get the configuration for audit logs.

Get the current audit logging configuration for the organization. Use this to verify how audit events are captured and retained.

No IAM permission required.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Monitoring

Access Prometheus metrics and monitoring data for API traffic, gateway health, and developer portal analytics.

Get provider portal monitoring data at a single point in time

See Prometheus instant queries for more information.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
query
required
string
Example: query=apisix

Prometheus expression query string.

Unix Timestamp (integer) or RFC3339 Timestamp (string)

Evaluation timestamp. Accepts either a Unix timestamp or an RFC3339 timestamp.

Float (number) or Duration (string)

Evaluation timeout, either as:

  • A float number in seconds (e.g. 2.5)
  • A duration string (e.g. 5s, 1.5m) in Prometheus-style format.
limit
integer

Maximum number of returned series. 0 means disabled.

portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get provider portal monitoring data over a range of time

See Prometheus range queries for more information.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
query
required
string
Example: query=apisix

Prometheus expression query string.

required
Unix Timestamp (integer) or RFC3339 Timestamp (string)

Start timestamp, inclusive. Accepts either a Unix timestamp or an RFC3339 timestamp.

required
Unix Timestamp (integer) or RFC3339 Timestamp (string)

End timestamp, inclusive. Accepts either a Unix timestamp or an RFC3339 timestamp.

required
Float (number) or Duration (string)

Query resolution step width, either as:

  • a float number in seconds (e.g. 15.5), or
  • a duration string (e.g. 15s, 1m, 2h) in Prometheus-style duration format.
Float (number) or Duration (string)

Evaluation timeout, either as:

  • A float number in seconds (e.g. 2.5)
  • A duration string (e.g. 5s, 1.5m) in Prometheus-style format.
limit
integer

Maximum number of returned series. 0 means disabled.

portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get data from Prometheus

Authorizations:
APIKeyAuthBasicAuth
path Parameters
required
Fixed Endpoints (string) or Dynamic Label Values Endpoint (string)

Prometheus HTTP API endpoint. See the Prometheus docs for the available URL query parameters for each endpoint.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get data from Prometheus

Authorizations:
APIKeyAuthBasicAuth
path Parameters
required
Fixed Endpoints (string) or Dynamic Label Values Endpoint (string)

Prometheus HTTP API endpoint. See the Prometheus docs for the available body parameters for each endpoint.

Request Body schema: application/x-www-form-urlencoded
property name*
additional property
any

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Debugger

Create debug sessions and inspect request/response traces to troubleshoot routing and plugin behavior on gateway groups.

Create a debug session

IAM Action: gateway:CreateDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

The object name.

description
string <= 65536 characters

The object description.

target_instances
required
Array of strings non-empty [ items [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$ ]
sampling_rule
Array of any or null

Sampling rules in lua-resty-expr format.

max_samples
integer [ 1 .. 200 ]
Default: 5

Maximum number of traces returned by the list API.

duration_secs
integer [ 10 .. 600 ]
Default: 60

Time-to-live in seconds for data plane configuration.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "description": "Object description.",
  • "target_instances": [
    ],
  • "sampling_rule": [
    ],
  • "max_samples": 5,
  • "duration_secs": 60
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List debug sessions

IAM Action: gateway:GetDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a debug session

IAM Action: gateway:GetDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

debug_session_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Debug session ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a debug session

IAM Action: gateway:DeleteDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

debug_session_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Debug session ID.

Responses

Response samples

Content type
application/json
""

Stop a debug session

IAM Action: gateway:StopDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

debug_session_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Debug session ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

List traces of a debug session

IAM Action: GetDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

debug_session_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Debug session ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a trace detail

IAM Action: GetDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

debug_session_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Debug session ID.

trace_id
required
string [ 1 .. 64 ] characters

Trace ID.

Responses

Response samples

Content type
application/json
{
  • "resourceSpans": [
    ]
}

Download a trace

IAM Action: gateway:ExportDebugSession, Resource: arn:api7:gateway:gatewaygroup/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
gateway_group_id
required
string >= 1
Example: 86fb9981-d9d2-4555-9df8-91ae92129335

Gateway group ID.

debug_session_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Debug session ID.

trace_id
required
string [ 1 .. 64 ] characters

Trace ID.

Responses

Response samples

Content type
application/json
{
  • "resourceSpans": [
    ]
}

Schema

Retrieve JSON schemas for core APISIX resources (services, routes, consumers, plugins) used for client-side validation.

Get schema by resource name

Get the schema definition for a specific resource type by name. This is useful when rendering dynamic forms or validating resource-specific request payloads.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
resource_name
required
string >= 1
Enum: "service" "upstream" "stream_service" "stream_upstream" "route" "consumer" "consumer_credential" "global_rule" "ssl" "vault_secret" "aws_secret" "kubernetes_secret" "plugin_metadata" "stream_route"
Example: consumer

Name of the resource.

Responses

Response samples

Content type
application/json
{
  • "value": { },
  • "description": "The consumer description.",
  • "properties": {
    },
  • "required": [
    ],
  • "type": "object"
}

Get schema definition of a plugin

Get schema definition of a plugin, including plugin meta properties and plugin properties.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
plugin_name
required
string [ 1 .. 64 ] characters

Name of the plugin.

query Parameters
subsystem
string
Default: "http"
Enum: "http" "stream"
Example: subsystem=stream

Type to filter the plugin list. http will only show L7 plugins and stream will only show L4 plugins.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get OpenAPI schema

The endpoint returns the request body schema of PUT/POST requests for users to understand how to structure a request.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
method
required
string >= 1
Enum: "POST" "PUT"

HTTP method to determine which request body to return.

path
required
string >= 1
Example: path=/apisix/admin/consumers

API endpoint.

Responses

Response samples

Content type
application/json
{
  • "value": { },
  • "description": "The consumer description.",
  • "properties": {
    },
  • "required": [
    ],
  • "type": "object"
}

Get core resources schema

Retrieve schema definitions for core gateway resources. Use these schemas to validate payload structures and build configuration tooling.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Variables

List all APISIX built-in variables available for use in route matching conditions and plugin configurations.

Get all variables

List all APISIX variables (including built-in NGINX variables) that can be used in route matching conditions and plugin configurations.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": [
    ]
}

System Settings

Manage global dashboard settings including SCIM provisioning, SMTP email server configuration, and admin security settings.

Update deployment settings

Update global system settings that control dashboard deployment behavior and platform-wide defaults. This operation affects configuration used across managed gateway resources.

Required IAM Permission: Action gateway:UpdateDeploymentSetting, Resource arn:api7:gateway:gatewaysetting/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
dp_manager_address
Array of strings <url_scheme_port> [ 0 .. 32 ] items unique [ items <url_scheme_port > non-empty [^\/]$ ]

DP manager address.

source
string
Enum: "database" "config"

The source of the control plane address and Admin API address.

admin_api_address
string <url_scheme>

The URL address of the Admin API.

file_server_address
string <url_scheme>

The URL address of the file server for serving uploaded files.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Get deployment settings

Retrieve current global deployment settings for the control plane. Use this endpoint to inspect active system-level configuration before making changes.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{}

Update SCIM settings

Update SCIM provisioning settings used for automated identity and user lifecycle synchronization. Changes here affect how external identity providers integrate with organization users.

Required IAM Permission: Action iam:UpdateSCIMProvisioning, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
enable_scim
boolean

Enable or disable the SCIM endpoint for provisioning and user management.

Responses

Request samples

Content type
application/json
{
  • "enable_scim": true
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get SCIM settings

Retrieve the current SCIM provisioning configuration for the organization. Use this to validate synchronization endpoints and provisioning status.

Required IAM Permission: Action iam:GetSCIMProvisioning, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Generate SCIM Token

Generate or rotate the SCIM access token used by external identity providers to call SCIM provisioning APIs. Rotating this token may require updating the provider configuration.

Required IAM Permission: Action iam:UpdateSCIMProvisioning, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": "a7scim-t1dJGY89gg8tqMwV2QunhV7472Z26C9VjE3mkZUfgIEpj0WJ1I7FGoEXG92SMYpEw9iciDB2gQI-default"
}

Update SMTP server settings

Update SMTP server configuration used for system email delivery, including notifications and verification emails. Ensure credentials and host settings are valid to avoid delivery failures.

Required IAM Permission: Action iam:UpdateSMTPServer, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
enable
required
boolean

Enable SMTP Server.

address
required
string <host_port>

The SMTP server address in host:port format.

authentication_type
string
Enum: "TLS" "STARTTLS"

The authentication type of the SMTP server.

ssl_verify
required
boolean

Whether to validate server-side SSL.

username
required
string

Username used to authenticate with the SMTP server.

password
required
string

Password used to authenticate with the SMTP server.

from_name
required
string^\s*("(?:[^"\\]|\\.)*"|([^<>@]+))?\s*$

Sender's name.

from_address
required
string <email>

Sender's email address.

Responses

Request samples

Content type
application/json
{
  • "enable": true,
  • "address": "smtp.example.com:587",
  • "authentication_type": "TLS",
  • "ssl_verify": true,
  • "username": "smtp-user@example.com",
  • "password": "secretpassword123",
  • "from_name": "John Doe",
  • "from_address": "sender@example.com"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get SMTP server settings

Retrieve the current SMTP server settings configured for outbound email delivery. Use this endpoint when auditing email configuration or debugging mail issues.

Required IAM Permission: Action iam:GetSMTPServer, Resource arn:api7:iam:organization/*

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get SMTP server settings status

Get the health and readiness status of the configured SMTP server settings. This endpoint helps verify whether current configuration can be used for email sending.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Developer Portal Settings

Configure developer portal access settings, including public visibility and custom domain configuration.

Update developer portal public access

Update public access and login behavior for a developer portal, such as how external users can access sign-in or registration flows. This setting controls portal exposure and authentication entry points.

Required IAM Permission: Action portal:UpdateDeveloperPortalPublicAccess, Resource arn:api7:portal:portal/%s/loginsetting/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
portal_public_access
boolean

If true, allow public access to the developer portal.

Responses

Request samples

Content type
application/json
{
  • "portal_public_access": true
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get developer portal public access

Get the current developer portal public access configuration for the specified portal. Use this to verify login and public accessibility settings.

Required IAM Permission: Action portal:GetDeveloperPortalPublicAccess, Resource arn:api7:portal:portal/%s/loginsetting/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Login Settings

Configure authentication providers (OIDC, SAML, LDAP, built-in) available for dashboard user login.

System Infos

Retrieve system information including the API7 EE version, deployment ID, deployment timestamp, license state, and free trial expiration.

Get all system infos

Retrieve system metadata for the dashboard environment, such as version details, license state, and runtime information used for administration and diagnostics.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Email

Manage email verification status for user accounts.

Check if an email is verified

Check whether the specified email address has completed verification. Use this to gate workflows that require verified contact information.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
email
required
string <email> [ 1 .. 255 ] characters

Email address.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get email verification

Verify an email address using the verification token and redirect to the corresponding result page. This endpoint is typically called from links sent in verification emails.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
token
required
string [ 1 .. 1024 ] characters

The token of the request.

Responses

Common

Utility endpoints shared across multiple resource types, such as version checks and resource name lookups.

Get Dashboard Version

Return the current dashboard version information. Use this endpoint for compatibility checks and operational diagnostics.

Authorizations:
APIKeyAuthBasicAuth

Responses

Response samples

Content type
application/json
{
  • "value": "dev"
}

Get resource names

Query resource names by conditions in the request payload to support selectors, autocomplete, or dependency checks in UI workflows.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
One of
resource_type
required
string
Enum: "gateway_group" "contact_point"

Resource type.

ids
required
Array of strings non-empty unique [ items non-empty ]

An array of resource IDs.

Responses

Request samples

Content type
application/json
Example
{
  • "resource_type": "gateway_group",
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Provider Portal - DCR Provider

Manage Dynamic Client Registration (DCR) providers that allow the developer portal to automatically register OAuth clients with identity providers.

Create an DCR provider

IAM Action: portal:CreateDCRProvider, Resource: arn:api7:portal:dcrprovider/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
name
required
string non-empty

The name of the Dynamic Client Registration (DCR) Provider.

provider_type
string
Default: "oidc"
Enum: "oidc" "http_bridge"

The type of DCR provider. Use "oidc" for standard OIDC Dynamic Client Registration (RFC 7591/7592), or "http_bridge" for a customer-implemented HTTP Bridge service.

issuer
required
string <uri>

The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation.

object

Provider-specific configuration. Required when provider_type is "http_bridge".

object

Custom headers to include in requests to the Authorization Server or HTTP Bridge.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "provider_type": "oidc",
  • "issuer": "http://example.com",
  • "provider_config": {},
  • "headers": {
    },
  • "desc": "Object description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all DCR providers

IAM Action: portal:GetDCRProvider, Resource: arn:api7:portal:dcrprovider/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get an DCR provider

IAM Action: portal:GetDCRProvider, Resource: arn:api7:portal:dcrprovider/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
dcr_provider_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the DCR Provider.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an DCR Provider

IAM Action: portal:UpdateDCRProvider, Resource: arn:api7:portal:dcrprovider/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
dcr_provider_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the DCR Provider.

Request Body schema: application/json
name
required
string non-empty

The name of the Dynamic Client Registration (DCR) Provider.

provider_type
string
Default: "oidc"
Enum: "oidc" "http_bridge"

The type of DCR provider. Use "oidc" for standard OIDC Dynamic Client Registration (RFC 7591/7592), or "http_bridge" for a customer-implemented HTTP Bridge service.

issuer
required
string <uri>

The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation.

object

Provider-specific configuration. Required when provider_type is "http_bridge".

object

Custom headers to include in requests to the Authorization Server or HTTP Bridge.

desc
string <= 65536 characters

The object description.

object

Key-value pairs of labels.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "provider_type": "oidc",
  • "issuer": "http://example.com",
  • "provider_config": {},
  • "headers": {
    },
  • "desc": "Object description.",
  • "labels": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an DCR Provider

IAM Action: portal:DeleteDCRProvider, Resource: arn:api7:portal:dcrprovider/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
dcr_provider_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the DCR Provider.

Responses

Response samples

Content type
application/json
""

Provider Portal - API Product

Manage API products — curated bundles of APIs exposed through the developer portal for external developer consumption.

Create an API product in Provider Portal

IAM Action: portal:CreateAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
One of
type
required
string
Default: "gateway"
Value: "gateway"
name
required
string [ 1 .. 100 ] characters

The object name.

logo
string

The base64-encoded logo image of the API product.

desc
string

The description of the API product.

object

Key-value pairs of labels.

object non-empty

The authentication configuration of the API product.

required
Array of objects non-empty

An array of gateway groups and services that the API product is linked to.

status
string
Default: "draft"
Enum: "draft" "published"

Status of the API product.

subscription_auto_approval
boolean
Default: false

If true, the subscription is automatically approved.

can_view_unsubscribed
boolean
Default: true

If true, developers can view the unsubscribed API.

visibility
string
Default: "public"
Enum: "public" "logged_in"

The visibility of the API product in the API hub. public means the product is visible to all users and logged_in means the product is only visible to logged-in developers.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "gateway",
  • "name": "Weather Insights API",
  • "logo": "string",
  • "desc": "The Weather Insights API provides real-time and historical weather data for any location worldwide.",
  • "labels": {
    },
  • "auth": {
    },
  • "linked_gateway_services": [
    ],
  • "status": "draft",
  • "subscription_auto_approval": false,
  • "can_view_unsubscribed": true,
  • "visibility": "public"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all API products in Provider Portal

IAM Action: portal:GetAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

service_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: service_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the published service.

portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get an API product in Provider Portal

IAM Action: portal:GetAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_product_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the API product.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an API product in Provider Portal

IAM Action: portal:UpdateAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_product_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the API product.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
One of
type
required
string
Default: "gateway"
Value: "gateway"
name
required
string [ 1 .. 100 ] characters

The object name.

logo
string

The base64-encoded logo image of the API product.

desc
string

The description of the API product.

object

Key-value pairs of labels.

object non-empty

The authentication configuration of the API product.

required
Array of objects non-empty

An array of gateway groups and services that the API product is linked to.

status
string
Default: "draft"
Enum: "draft" "published"

Status of the API product.

subscription_auto_approval
boolean
Default: false

If true, the subscription is automatically approved.

can_view_unsubscribed
boolean
Default: true

If true, developers can view the unsubscribed API.

visibility
string
Default: "public"
Enum: "public" "logged_in"

The visibility of the API product in the API hub. public means the product is visible to all users and logged_in means the product is only visible to logged-in developers.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "gateway",
  • "name": "Weather Insights API",
  • "logo": "string",
  • "desc": "The Weather Insights API provides real-time and historical weather data for any location worldwide.",
  • "labels": {
    },
  • "auth": {
    },
  • "linked_gateway_services": [
    ],
  • "status": "draft",
  • "subscription_auto_approval": false,
  • "can_view_unsubscribed": true,
  • "visibility": "public"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Patch an API product in Provider Portal

IAM Action: portal:UpdateAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_product_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the API product.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
Array
One of
op
required
string
Enum: "add" "replace"

The operation to be performed.

path
required
string

Path to the field to be replaced or added. Path should follow the JSON Pointer format.

value
required
any

Value to be added or replaced.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an API product in Provider Portal

IAM Action: portal:DeleteAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_product_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the API product.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
""

List all subscriptions in Provider Portal for an API product

IAM Action: portal:GetAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_product_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the API product.

query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "subscribed_at"
Enum: "developer_name" "subscribed_at"
search
string
Example: search=version%3Dv2

Condition to search resources by.

labels
string non-empty
Example: labels=labels%5Bversion%5D=v2

Label(s) to filter resources by. The format is labels[key]=value and should be URL-encoded.

portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Cancel a subscription in Provider Portal for an API product

IAM Action: portal:UpdateAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_product_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the API product.

subscription_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

the unique identifier of the subscription.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
""

List all notification histories for an API product

IAM Action: portal:GetAPIProduct, Resource: arn:api7:portal:portal/%s/apiproduct/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_product_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the API product.

query Parameters
notification_type
string
Enum: "email" "webhook"

The type of the notification.

event
string
Enum: "subscription_approval_created" "subscription_approval_accepted" "subscription_approval_rejected" "subscription_cancelled"

Notification trigger.

contact_point_id
string
Example: contact_point_id=6c97bc5f-3356-41f5-894c-c88df5389bd2

The contact point ID of the notification.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "notified_at"
Value: "notified_at"

Order to list the notifications by.

portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Provider Portal - Portal Instance

Manage developer portal instances, including their configuration, custom domains, and appearance settings.

List all portal instances

IAM Action: portal:ListPortals, Resource: arn:api7:portal:portal/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "updated_at"
Enum: "created_at" "updated_at"

Index to order resources by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create a portal instance

IAM Action: portal:CreatePortal, Resource: arn:api7:portal:portal/*

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Portal instance name.

object

Labels of the portal instance.

public_url
required
string <url> non-empty

Portal instance public URL.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get a portal instance

IAM Action: portal:GetPortal, Resource: arn:api7:portal:portal/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
portal_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a portal instance

IAM Action: portal:UpdatePortal, Resource: arn:api7:portal:portal/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
portal_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Portal instance name.

object

Labels of the portal instance.

public_url
required
string <url> non-empty

Portal instance public URL.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a portal instance

IAM Action: portal:DeletePortal, Resource: arn:api7:portal:portal/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
portal_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
""

Provider Portal - Portal Token

Manage access tokens for authenticating developer portal API requests.

Create a portal token

IAM Action: portal:CreatePortalToken, Resource: arn:api7:portal:portal/%s/token/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
name
required
string <= 256 characters

The portal token name.

expires_at
integer <int32>

The expiration timestamp of the portal token. 0 means the token will not expire.

Responses

Request samples

Content type
application/json
{
  • "name": "my-portal-token",
  • "expires_at": 1752288235
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

List all portal tokens

IAM Action: portal:GetPortalToken, Resource: arn:api7:portal:portal/%s/token/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

order_by
string
Default: "created_at"
Enum: "created_at" "updated_at" "expires_at"

Index to order the portal tokens by.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Get a portal token

IAM Action: portal:GetPortalToken, Resource: arn:api7:portal:portal/%s/token/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
portal_token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal token.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update a portal token

IAM Action: portal:UpdatePortalToken, Resource: arn:api7:portal:portal/%s/token/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
portal_token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal token.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
name
required
string <= 256 characters

The portal token name.

Responses

Request samples

Content type
application/json
{
  • "name": "my-portal-token"
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete a portal token

IAM Action: portal:DeletePortalToken, Resource: arn:api7:portal:portal/%s/token/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
portal_token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal token.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Regenerate a portal token

IAM Action: portal:UpdatePortalToken, Resource: arn:api7:portal:portal/%s/token/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
portal_token_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal token.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Request Body schema: application/json
expires_at
required
integer <int32>

The expiration timestamp of the portal token. 0 means the token will not expire.

Responses

Request samples

Content type
application/json
{
  • "expires_at": 1752288235
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Developer

Manage developer accounts registered through the developer portal, including invitations and access control.

List Developers

IAM Action: portal:GetDeveloper, Resource: arn:api7:portal:portal/%s/developer/%s

Authorizations:
APIKeyAuthBasicAuth
query Parameters
page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "last_active_at"
Enum: "last_active_at" "created_at"

Index to order developers by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Delete a developer

IAM Action: portal:DeleteDeveloper, Resource: arn:api7:portal:portal/%s/developer/%s

Authorizations:
APIKeyAuthBasicAuth
path Parameters
developer_external_id
required
string
Example: dev1

Developer external ID.

query Parameters
portal_id
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Default: "default"
Example: portal_id=bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

The unique identifier of the portal instance.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Approval

Manage approval workflows for developer subscription requests to API products.

List approvals

List pending and processed approval workflow items for developer portal operations, such as API product subscriptions and developer registrations. Use filters to review approvals by status, event type, operator, applicant, and resource.

Required IAM Permission: For event type api_product_subscription: Action portal:ApproveAPIProductSubscription, Resource arn:api7:portal:portal/%s/apiproduct/%s; for event type developer_registration: Action portal:ApproveDeveloperSignUp, Resource arn:api7:portal:portal/%s/developer/*

Authorizations:
APIKeyAuthBasicAuth
query Parameters
status
string
Enum: "pending" "finished"

Approval status.

result
string
Enum: "accepted" "rejected" "cancelled"

Approval outcome.

event
string
Enum: "api_product_subscription" "developer_registration"

Approval event.

resource_type
string
Enum: "api_product" "developer"

Resource type.

resource_name
string

Resource name.

operator_name
string

Operator name.

applicant_name
string

Applicant name.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

order_by
string
Default: "applied_at"
Enum: "applied_at" "resource_name" "operated_at"

Index to order approvals by.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Accept an approval request

Approve a specific workflow request and apply the corresponding portal-side change, such as granting an API product subscription or accepting a developer sign-up. This operation advances the approval lifecycle to an accepted state.

Required IAM Permission: For event type api_product_subscription: Action portal:ApproveAPIProductSubscription, Resource arn:api7:portal:portal/%s/apiproduct/%s; for event type developer_registration: Action portal:ApproveDeveloperSignUp, Resource arn:api7:portal:portal/%s/developer/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
approval_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Approval ID.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

Reject an approval request

Reject a specific workflow approval request so the requested action is not applied. Use this endpoint to explicitly deny subscription or registration requests that do not meet review criteria.

Required IAM Permission: For event type api_product_subscription: Action portal:ApproveAPIProductSubscription, Resource arn:api7:portal:portal/%s/apiproduct/%s; for event type developer_registration: Action portal:ApproveDeveloperSignUp, Resource arn:api7:portal:portal/%s/developer/*

Authorizations:
APIKeyAuthBasicAuth
path Parameters
approval_id
required
string [ 1 .. 256 ] characters ^[a-zA-Z0-9-_.]+$
Example: bd58fce2-b6cc-4d2d-a53c-6ce11b19c101

Approval ID.

Responses

Response samples

Content type
application/json
{
  • "value": { }
}

AI Gateway Group

Manage AI Gateway groups — logical clusters of AISIX AI Gateway instances. Each group shares the same control plane configuration.

List all AI Gateway groups

Returns a paginated list of all AI Gateway groups (AISIX clusters).

Authorizations:
APIKeyAuthBasicAuth
query Parameters
direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create an AI Gateway group

IAM Action: ai_gateway:CreateAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/* Creates a new AI Gateway group (AISIX cluster).

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

The object name.

description
string

AI Gateway group description.

object

Configuration for the AI Gateway group.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "description": "My AI Gateway group.",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get an AI Gateway group

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns the specified AI Gateway group by ID.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an AI Gateway group

IAM Action: ai_gateway:UpdateAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Updates the name, description, or configuration of the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

The object name.

description
string

AI Gateway group description.

object

Configuration for the AI Gateway group.

Responses

Request samples

Content type
application/json
{
  • "name": "us-west-rsc",
  • "description": "My AI Gateway group.",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an AI Gateway group

IAM Action: ai_gateway:DeleteAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Deletes the specified AI Gateway group and all its associated instances.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

Responses

Response samples

Content type
application/json
""

List AI Gateway instances in a group

IAM Action: ai_gateway:GetAIGatewayInstance, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns all AI Gateway instances (AISIX nodes) registered in the specified group. Instance status is computed dynamically from the last heartbeat time: Healthy within 60 seconds, LostConnection between 60 seconds and 2 hours, Offline beyond 2 hours.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Delete a single AI Gateway instance

IAM Action: ai_gateway:DeleteAIGatewayInstance, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Removes the specified AI Gateway instance from its group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

ai_gateway_instance_id
required
string non-empty
Example: aisix-node-001

AI Gateway instance ID.

Responses

Response samples

Content type
application/json
""

Generate a Docker run command to install an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a docker run command that configures and starts an AISIX AI Gateway instance connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

name
string non-empty

The hostname of the gateway.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
docker run -d \
  -e API7_CONTROL_PLANE_ENDPOINTS='["https://10.0.0.1:31344"]' \
  -e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----" \
  -e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
  ...
  -----END PRIVATE KEY-----" \
  -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----" \
  -p 3000:3000 \
  api7/aisix:latest

Generate a Docker Compose file to install an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a Docker Compose configuration that starts an AISIX AI Gateway instance connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

name
string non-empty
Default: "api7-ee-3-gateway"

The name of the docker compose container and service.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
services:
  ai-gateway:
    image: api7/aisix:latest
    container_name: ai-gateway
    restart: always
    ports:
      - "3000:3000"
    environment:
      API7_CONTROL_PLANE_ENDPOINTS: '["https://10.0.0.1:31344"]'

Generate a Helm install script for an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a shell script that uses Helm to install an AISIX AI Gateway instance in Kubernetes, connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

extra_values[]
Array of strings
Example: extra_values[]=a=b&extra_values[]=c=d

Extra values to be passed to the Helm chart, in the form of key=value.

Responses

Response samples

Content type
text/plain
helm repo add api7 https://charts.api7.ai
helm repo update
helm upgrade --install -n default --create-namespace ai-gateway api7/aisix \
  --set "extraEnvVars[0].name=API7_CONTROL_PLANE_ENDPOINTS" \
  --set-string 'extraEnvVars[0].value=["https://10.0.0.1:31344"]' \
  --set "extraEnvVars[1].name=API7_CONTROL_PLANE_CERT" \
  --set "extraEnvVars[1].valueFrom.secretKeyRef.name=ai-gateway-tls" \
  --set "extraEnvVars[1].valueFrom.secretKeyRef.key=tls.crt" \
  --set "extraEnvVars[2].name=API7_CONTROL_PLANE_KEY" \
  --set "extraEnvVars[2].valueFrom.secretKeyRef.name=ai-gateway-tls" \
  --set "extraEnvVars[2].valueFrom.secretKeyRef.key=tls.key" \
  --set "extraEnvVars[3].name=API7_CONTROL_PLANE_CA" \
  --set "extraEnvVars[3].valueFrom.secretKeyRef.name=ai-gateway-tls" \
  --set "extraEnvVars[3].valueFrom.secretKeyRef.key=ca.crt" \
  --set "image.tag=latest"

Generate a Helm values YAML for an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a Helm values YAML file for deploying an AISIX AI Gateway instance in Kubernetes, connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

Responses

Response samples

Content type
text/plain
extraEnvVars:
- name: API7_CONTROL_PLANE_ENDPOINTS
  value: '["https://10.0.0.1:31344"]'
- name: API7_CONTROL_PLANE_CERT
  valueFrom:
    secretKeyRef:
      name: ai-gateway-tls
      key: tls.crt
- name: API7_CONTROL_PLANE_KEY
  valueFrom:
    secretKeyRef:
      name: ai-gateway-tls
      key: tls.key
- name: API7_CONTROL_PLANE_CA
  valueFrom:
    secretKeyRef:
      name: ai-gateway-tls
      key: ca.crt
image:
  tag: latest

Issue an AI data plane certificate

Issues a client mTLS certificate for an aisix-ee AI Gateway instance to authenticate with the control plane (dp-manager). Use this during aisix-ee bootstrap or certificate rotation.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

AI Gateway Instance

View and manage individual AISIX AI Gateway nodes running within an AI Gateway group. Monitor instance health and connection status.

List AI Gateway instances in a group

IAM Action: ai_gateway:GetAIGatewayInstance, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns all AI Gateway instances (AISIX nodes) registered in the specified group. Instance status is computed dynamically from the last heartbeat time: Healthy within 60 seconds, LostConnection between 60 seconds and 2 hours, Offline beyond 2 hours.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Delete a single AI Gateway instance

IAM Action: ai_gateway:DeleteAIGatewayInstance, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Removes the specified AI Gateway instance from its group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

ai_gateway_instance_id
required
string non-empty
Example: aisix-node-001

AI Gateway instance ID.

Responses

Response samples

Content type
application/json
""

Generate a Docker run command to install an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a docker run command that configures and starts an AISIX AI Gateway instance connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

name
string non-empty

The hostname of the gateway.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
docker run -d \
  -e API7_CONTROL_PLANE_ENDPOINTS='["https://10.0.0.1:31344"]' \
  -e API7_CONTROL_PLANE_CERT="-----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----" \
  -e API7_CONTROL_PLANE_KEY="-----BEGIN PRIVATE KEY-----
  ...
  -----END PRIVATE KEY-----" \
  -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----" \
  -p 3000:3000 \
  api7/aisix:latest

Generate a Docker Compose file to install an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a Docker Compose configuration that starts an AISIX AI Gateway instance connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

image
string non-empty
Example: image=api7/api7-ee-3-gateway

Docker image.

http_port
integer
Default: 9080

The HTTP port of the gateway.

name
string non-empty
Default: "api7-ee-3-gateway"

The name of the docker compose container and service.

extra_args[]
Array of strings
Example: extra_args[]=a=b&extra_args[]=c=d

Additional docker run arguments.

Responses

Response samples

Content type
text/plain
services:
  ai-gateway:
    image: api7/aisix:latest
    container_name: ai-gateway
    restart: always
    ports:
      - "3000:3000"
    environment:
      API7_CONTROL_PLANE_ENDPOINTS: '["https://10.0.0.1:31344"]'

Generate a Helm install script for an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a shell script that uses Helm to install an AISIX AI Gateway instance in Kubernetes, connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

extra_values[]
Array of strings
Example: extra_values[]=a=b&extra_values[]=c=d

Extra values to be passed to the Helm chart, in the form of key=value.

Responses

Response samples

Content type
text/plain
helm repo add api7 https://charts.api7.ai
helm repo update
helm upgrade --install -n default --create-namespace ai-gateway api7/aisix \
  --set "extraEnvVars[0].name=API7_CONTROL_PLANE_ENDPOINTS" \
  --set-string 'extraEnvVars[0].value=["https://10.0.0.1:31344"]' \
  --set "extraEnvVars[1].name=API7_CONTROL_PLANE_CERT" \
  --set "extraEnvVars[1].valueFrom.secretKeyRef.name=ai-gateway-tls" \
  --set "extraEnvVars[1].valueFrom.secretKeyRef.key=tls.crt" \
  --set "extraEnvVars[2].name=API7_CONTROL_PLANE_KEY" \
  --set "extraEnvVars[2].valueFrom.secretKeyRef.name=ai-gateway-tls" \
  --set "extraEnvVars[2].valueFrom.secretKeyRef.key=tls.key" \
  --set "extraEnvVars[3].name=API7_CONTROL_PLANE_CA" \
  --set "extraEnvVars[3].valueFrom.secretKeyRef.name=ai-gateway-tls" \
  --set "extraEnvVars[3].valueFrom.secretKeyRef.key=ca.crt" \
  --set "image.tag=latest"

Generate a Helm values YAML for an AI Gateway instance

IAM Action: ai_gateway:GetAIGatewayGroup, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Generates a Helm values YAML file for deploying an AISIX AI Gateway instance in Kubernetes, connected to the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

query Parameters
dp_manager_address
string non-empty
Example: dp_manager_address=10.15.101.5

The IP address of the control plane.

validity_period
integer [ 1 .. 10950 ]
Default: 3650

The validity period of the certificate in days.

name
required
string

Gateway name.

namespace
required
string

Gateway namespace.

service_account
string

Service account to install the gateway.

replicas
integer
Default: 1

The number of replicas.

workers
integer
Example: workers=5

The number of worker processes for the gateway instance. By default, it is configured to match the number of CPU cores on the server hosting the gateway instance.

cpu_limit
string
Example: cpu_limit=6

The CPU limit in number of cores.

memory_limit
string
Example: memory_limit=6Gi

The memory limit. Use the format <number><unit>.

Responses

Response samples

Content type
text/plain
extraEnvVars:
- name: API7_CONTROL_PLANE_ENDPOINTS
  value: '["https://10.0.0.1:31344"]'
- name: API7_CONTROL_PLANE_CERT
  valueFrom:
    secretKeyRef:
      name: ai-gateway-tls
      key: tls.crt
- name: API7_CONTROL_PLANE_KEY
  valueFrom:
    secretKeyRef:
      name: ai-gateway-tls
      key: tls.key
- name: API7_CONTROL_PLANE_CA
  valueFrom:
    secretKeyRef:
      name: ai-gateway-tls
      key: ca.crt
image:
  tag: latest

Issue an AI data plane certificate

Issues a client mTLS certificate for an aisix-ee AI Gateway instance to authenticate with the control plane (dp-manager). Use this during aisix-ee bootstrap or certificate rotation.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
ai_gateway_group_id
required
string non-empty
Example: abc1234567890

AI Gateway group ID.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Configuration

Validate batch configuration

Validate a batch of APISIX declarative configurations including routes, services, consumers, upstreams, etc. Performs resource-level JSON Schema validation, plugin check_schema advanced validation, and duplicate ID detection. Returns all validation errors at once.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
routes
Array of objects
services
Array of objects
consumers
Array of objects
upstreams
Array of objects
ssls
Array of objects
global_rules
Array of objects
stream_routes
Array of objects
plugin_metadata
Array of objects
plugin_configs
Array of objects
consumer_groups
Array of objects

Responses

Request samples

Content type
application/json
{
  • "routes": [
    ],
  • "services": [
    ],
  • "consumers": [
    ],
  • "upstreams": [
    ],
  • "ssls": [
    ],
  • "global_rules": [
    ],
  • "stream_routes": [
    ],
  • "plugin_metadata": [
    ],
  • "plugin_configs": [
    ],
  • "consumer_groups": [
    ]
}

Response samples

Content type
application/json
""

File

Upload a file

Upload a file to the control plane. The file is stored compressed in the database. Returns the file ID which can be used to construct a dp-manager URL for plugin configuration.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
name
required
string
Example: name=petstore-api.json

Original file name.

Request Body schema: application/octet-stream

Raw file content (maximum 10 MiB).

Schema not provided

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Download file content

Download the original content of an uploaded file.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
file_id
required
string

The unique identifier of the file.

Responses

Response samples

Content type
"string"

Model Catalog

List model catalog entries

IAM Action: ai_gateway:ListModelCatalogs, Resource: arn:api7:ai_gateway:modelcatalog/* Returns globally synchronized model catalog entries that can be used to populate AI model selections. Set compact=true to receive the reduced dropdown-oriented item shape.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

search
string
Example: search=version%3Dv2

Condition to search resources by.

order_by
string
Default: "provider"
Enum: "provider" "model" "name" "status" "created_at" "updated_at"

Field used to order catalog entries.

provider
string
Example: provider=gemini

Filter catalog entries by canonical provider.

status
string
Enum: "active" "deprecated"

Filter catalog entries by status.

compact
boolean
Default: false

Return the compact dropdown-oriented item shape when true.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Trigger a manual model catalog sync

IAM Action: ai_gateway:SyncModelCatalog, Resource: arn:api7:ai_gateway:modelcatalog/* Triggers an immediate synchronization against the configured upstream model catalog endpoint. Remote fetch failures are returned as HTTP 200 with success=false; HTTP 409 is reserved for concurrent sync attempts.

Authorizations:
APIKeyAuthBasicAuth
Request Body schema: application/json
optional
object

Empty request body reserved for future manual sync options.

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "value": {
    }
}

List model catalog sync logs

IAM Action: ai_gateway:ListModelSyncLogs, Resource: arn:api7:ai_gateway:modelcatalog/* Returns synchronization history entries, including execution status and structured diff information.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

order_by
string
Default: "started_at"
Enum: "started_at" "completed_at" "duration_ms" "http_status" "status" "trigger_type" "created_at"

Field used to order sync log entries.

trigger_type
string
Enum: "scheduled" "manual"

Filter logs by trigger source.

status
string
Enum: "running" "success" "failed"

Filter logs by execution status.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

AI Model

List AI models in a group

IAM Action: ai_gateway:ListAIModels, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns all AI model configurations in the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create an AI model

IAM Action: ai_gateway:CreateAIModel, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Creates a new AI model configuration in the specified AI Gateway group. The model will be synced to the aisix data plane via etcd.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Request Body schema: application/json
required
name
required
string <= 256 characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

Human-readable name for the model. Used as the model identifier in aisix proxy requests.

model
required
string [ 1 .. 256 ] characters

Underlying model identifier used by the provider.

provider_id
required
string [ 1 .. 256 ] characters

ID of the AIProvider that supplies credentials for this model. The provider must belong to the same AI Gateway group.

timeout
integer <int64> >= 0

Request timeout in milliseconds.

object

Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).

Responses

Request samples

Content type
application/json
{
  • "name": "my-gpt4o",
  • "model": "gpt-4o",
  • "provider_id": "provider-abc123",
  • "timeout": 30000,
  • "rate_limit": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get an AI model

IAM Action: ai_gateway:GetAIModel, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns the specified AI model configuration by ID.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
model_id
required
string non-empty
Example: model-abc123

AI Model ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an AI model

IAM Action: ai_gateway:UpdateAIModel, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Updates the specified AI model configuration. Changes are synced to the aisix data plane via etcd.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
model_id
required
string non-empty
Example: model-abc123

AI Model ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Request Body schema: application/json
required
name
required
string <= 256 characters ^[A-Za-z0-9][A-Za-z0-9._:/-]*$

Human-readable name for the model. Used as the model identifier in aisix proxy requests.

model
required
string [ 1 .. 256 ] characters

Underlying model identifier used by the provider.

provider_id
required
string [ 1 .. 256 ] characters

ID of the AIProvider that supplies credentials for this model. The provider must belong to the same AI Gateway group.

timeout
integer <int64> >= 0

Request timeout in milliseconds.

object

Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).

Responses

Request samples

Content type
application/json
{
  • "name": "my-gpt4o",
  • "model": "gpt-4o",
  • "provider_id": "provider-abc123",
  • "timeout": 30000,
  • "rate_limit": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an AI model

IAM Action: ai_gateway:DeleteAIModel, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Deletes the specified AI model configuration and removes it from etcd.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
model_id
required
string non-empty
Example: model-abc123

AI Model ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Responses

Response samples

Content type
application/json
""

AI API Key

List AI API keys in a group

IAM Action: ai_gateway:ListAIAPIKeys, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns all AI API key configurations in the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create an AI API key

IAM Action: ai_gateway:CreateAIAPIKey, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Creates a new AI API key in the specified AI Gateway group. The key will be synced to the aisix data plane via etcd.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Request Body schema: application/json
required
name
string <= 256 characters

Optional human-readable label for the API key (control-plane only, not written to the data plane).

key
required
string [ 1 .. 256 ] characters

The secret key value used for authentication.

allowed_models
required
Array of strings

Required. List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.

object

Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).

Responses

Request samples

Content type
application/json
{
  • "name": "my-app-key",
  • "key": "my-secret-key-value",
  • "allowed_models": [
    ],
  • "rate_limit": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get an AI API key

IAM Action: ai_gateway:GetAIAPIKey, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns the specified AI API key configuration by ID.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_key_id
required
string non-empty
Example: apikey-abc123

AI API Key ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an AI API key

IAM Action: ai_gateway:UpdateAIAPIKey, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Updates the specified AI API key configuration. Changes are synced to the aisix data plane via etcd.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_key_id
required
string non-empty
Example: apikey-abc123

AI API Key ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Request Body schema: application/json
required
name
string <= 256 characters

Optional human-readable label for the API key (control-plane only, not written to the data plane).

key
required
string [ 1 .. 256 ] characters

The secret key value used for authentication.

allowed_models
required
Array of strings

Required. List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.

object

Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).

Responses

Request samples

Content type
application/json
{
  • "name": "my-app-key",
  • "key": "my-secret-key-value",
  • "allowed_models": [
    ],
  • "rate_limit": {
    }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an AI API key

IAM Action: ai_gateway:DeleteAIAPIKey, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Deletes the specified AI API key configuration and removes it from etcd.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
api_key_id
required
string non-empty
Example: apikey-abc123

AI API Key ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Responses

Response samples

Content type
application/json
""

AI Provider

List AI providers in a group

IAM Action: ai_gateway:ListAIProviders, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns all AI provider configurations in the specified AI Gateway group.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

direction
string
Default: "desc"
Enum: "asc" "desc"

Order to list the resources by. The sorting index follows the configuration of order_by.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 1
}

Create an AI provider

IAM Action: ai_gateway:CreateAIProvider, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Creates a new AI provider configuration in the specified AI Gateway group. The provider will be synced to the aisix data plane via etcd.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Request Body schema: application/json
required
name
required
string <= 256 characters

Human-readable name for the provider.

type
required
string
Enum: "openai" "anthropic" "azure" "bedrock" "deepseek" "gemini" "openrouter"

Provider type. Determines the shape of the config object.

config
required
object

Provider credentials. Shape depends on the type: - openai/anthropic/deepseek/gemini/openrouter: { api_key, api_base? } - azure: { api_key, api_base (required), api_version? } - bedrock: { region, access_key_id, secret_access_key, session_token?, endpoint? }

Responses

Request samples

Content type
application/json
{
  • "name": "my-openai-provider",
  • "type": "openai",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Get an AI provider

IAM Action: ai_gateway:GetAIProvider, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Returns the specified AI provider configuration by ID.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
provider_id
required
string non-empty
Example: provider-abc123

AI Provider ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Update an AI provider

IAM Action: ai_gateway:UpdateAIProvider, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Updates the specified AI provider configuration. Changes are synced to the aisix data plane via etcd.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
provider_id
required
string non-empty
Example: provider-abc123

AI Provider ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Request Body schema: application/json
required
name
required
string <= 256 characters

Human-readable name for the provider.

type
required
string
Enum: "openai" "anthropic" "azure" "bedrock" "deepseek" "gemini" "openrouter"

Provider type. Determines the shape of the config object.

config
required
object

Provider credentials. Shape depends on the type: - openai/anthropic/deepseek/gemini/openrouter: { api_key, api_base? } - azure: { api_key, api_base (required), api_version? } - bedrock: { region, access_key_id, secret_access_key, session_token?, endpoint? }

Responses

Request samples

Content type
application/json
{
  • "name": "my-openai-provider",
  • "type": "openai",
  • "config": { }
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Delete an AI provider

IAM Action: ai_gateway:DeleteAIProvider, Resource: arn:api7:ai_gateway:aigatewaygroup/%s Deletes the specified AI provider configuration and removes it from etcd. Returns 409 Conflict if any AI models reference this provider.

Authorizations:
APIKeyAuthBasicAuth
path Parameters
provider_id
required
string non-empty
Example: provider-abc123

AI Provider ID.

query Parameters
ai_gateway_group_id
required
string non-empty
Example: ai_gateway_group_id=abc1234567890

AI Gateway group ID (filter resources by group).

Responses

Response samples

Content type
application/json
""

AI Gateway Log

List AI gateway span logs

IAM Action: ai_gateway:ListAIGatewayLogs, Resource: arn:api7:ai_gateway:aigatewaygroup/* Returns a paginated list of AI/LLM span logs extracted from OTLP traces sent by AI gateway dataplanes.

Authorizations:
APIKeyAuthBasicAuth
query Parameters
ai_gateway_group_id
string

Filter logs by AI gateway group ID.

instance_id
string

Filter logs by dataplane instance ID.

model
string

Filter logs by model name.

start_time
string <date-time>

Filter logs with start_time >= this value (RFC3339 format).

end_time
string <date-time>

Filter logs with start_time < this value (RFC3339 format).

page
integer <int32> >= 1

Page number of the listed resources. Used together with page_size. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

page_size
integer <int32> >= 1

Number of resources listed per page. Used together with page. For example, when there are 13 resources in total, if the query parameters are page=1&page_size=10, the GET response will show the route total as 13 and display 10 resources in the first page. If the query parameters are page=2&page_size=10, the GET response will show the route total as 13 and display 3 resources in the second page.

Responses

Response samples

Content type
application/json
{
  • "list": [
    ],
  • "total": 0
}