{ "openapi": "3.0.1", "info": { "title": "API7 Enterprise Admin APIs", "description": "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.\n\n## Base URL\n\nAll API paths are relative to your API7 Dashboard address, e.g. `https://your-api7-dashboard:7443`.\n\n## Authentication\n\nEvery request must include one of the following credentials:\n\n- **API Key**: Pass a valid API key in the `X-API-KEY` HTTP header.\n- **Basic Auth**: Use HTTP Basic Authentication with a dashboard user's credentials.\n\n## Two API Path Styles\n\nAPI7 Enterprise exposes two families of endpoints:\n\n| Path prefix | Purpose |\n|---|---|\n| `/api/...` | Dashboard management APIs for services, gateway groups, users, roles, and all other resources. |\n| `/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. |\n\n## Key Concepts\n\n- **Service Template** — A reusable API definition (upstream, routes, plugins) that is not yet deployed. Think of it as a blueprint.\n- **Published Service** — A service template deployed to a specific gateway group, actively handling live traffic.\n- **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.\n- **Gateway Instance** — An individual APISIX gateway node running inside a gateway group.\n- **Consumer** — An API consumer identity used for authentication and rate limiting, scoped to a gateway group.\n- **Route** — A traffic matching rule (host, path, HTTP method) that belongs to a service template.\n- **Stream Route** — A Layer 4 (TCP/UDP) route for non-HTTP proxying.\n- **Runtime Configuration** — Per-gateway-group overrides applied to a published service (e.g., different upstreams or plugin settings).\n- **Global Rule** — Plugins applied to every request across an entire gateway group.\n- **Secret Provider** — Integration with external secret managers (HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets).\n\n## Response Format\n\nAll JSON responses follow an envelope structure:\n\n- **Single resource**: `{ \"value\": { ... } }`\n- **List of resources**: `{ \"list\": [ ... ], \"total\": 42 }`\n- **Error**: `{ \"error_msg\": \"description of the error\" }`\n\nPagination is controlled via `page` (1-indexed) and `page_size` query parameters.", "version": "3.9.16" }, "servers": [], "security": [ { "APIKeyAuth": [] }, { "BasicAuth": [] } ], "tags": [ { "name": "Service Template", "description": "Manage reusable service definitions (upstream, routes, plugins) that serve as blueprints before deployment." }, { "name": "Published Service", "description": "Manage services deployed to a specific gateway group. Published services actively handle live API traffic." }, { "name": "Route", "description": "Manage HTTP routes (host, path, method matching rules) that belong to a service template." }, { "name": "Stream Route", "description": "Manage Layer 4 (TCP/UDP) stream routes for non-HTTP proxying within a service template." }, { "name": "Consumer", "description": "Manage API consumer identities used for authentication, authorization, and rate limiting. Consumers are scoped to a gateway group." }, { "name": "Gateway Group", "description": "Manage gateway groups — logical clusters of gateway instances sharing configuration. Resources like consumers and published services are scoped to a gateway group." }, { "name": "Gateway Instance", "description": "View and manage individual APISIX gateway nodes running within a gateway group. Monitor instance health, status, and resource usage." }, { "name": "SSL", "description": "Manage SSL/TLS certificates and keys used for HTTPS traffic encryption on gateway groups." }, { "name": "Certificate", "description": "Manage TLS client certificates for mutual TLS (mTLS) authentication between gateways and upstream services." }, { "name": "CACertificate", "description": "Manage Certificate Authority (CA) certificates used to verify client certificates in mTLS authentication." }, { "name": "SNI", "description": "Manage Server Name Indication (SNI) mappings that associate domain names with SSL certificates for TLS termination." }, { "name": "Global Rule", "description": "Manage plugins applied to all incoming requests across an entire gateway group, regardless of the matched route." }, { "name": "Plugin", "description": "Browse available plugins, retrieve their JSON schemas, and view usage details across resources." }, { "name": "Plugin Metadata", "description": "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)." }, { "name": "Custom Plugin", "description": "Upload, manage, and deploy custom Lua and WebAssembly (WASM) plugins to extend gateway functionality beyond the built-in plugin set." }, { "name": "Secret Provider", "description": "Manage integrations with external secret managers (HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets) used to store sensitive plugin configuration." }, { "name": "Proto", "description": "Manage Protocol Buffer (protobuf) definitions used by the gRPC transcoding plugin to convert between HTTP/JSON and gRPC." }, { "name": "Service Registry", "description": "Manage connections to external service registries (Kubernetes, Nacos, Consul) for automatic upstream service discovery." }, { "name": "User", "description": "Manage dashboard user accounts, including invitations, profile updates, password management, and authentication (login/logout via OIDC, SAML, LDAP, or built-in credentials)." }, { "name": "Role", "description": "Manage RBAC roles that group permissions and can be assigned to users to control access to dashboard resources." }, { "name": "Permission Policy", "description": "Define fine-grained IAM permission policies specifying which actions are allowed or denied on specific resource types." }, { "name": "Token", "description": "Manage API access tokens (API keys) for programmatic authentication with the dashboard APIs." }, { "name": "Dashboard Login Option", "description": "Configure authentication providers (OIDC, SAML, LDAP, built-in) available on the dashboard and developer portal login pages." }, { "name": "License", "description": "View and import the API7 Enterprise license that governs feature availability and usage limits." }, { "name": "Label", "description": "Retrieve all labels (key-value pairs) currently applied across resources for filtering and organization." }, { "name": "Alert", "description": "Manage alert policies that monitor API metrics and trigger notifications when configurable thresholds are breached." }, { "name": "Contact Point", "description": "Manage notification channels (Webhook, Slack, email, etc.) used to deliver alert notifications." }, { "name": "Audit Logs", "description": "Query and export audit log entries that record every administrative action performed on the dashboard." }, { "name": "Audit Config", "description": "Configure audit logging behavior, such as retention period and which events to record." }, { "name": "Monitoring", "description": "Access Prometheus metrics and monitoring data for API traffic, gateway health, and developer portal analytics." }, { "name": "Debugger", "description": "Create debug sessions and inspect request/response traces to troubleshoot routing and plugin behavior on gateway groups." }, { "name": "Schema", "description": "Retrieve JSON schemas for core APISIX resources (services, routes, consumers, plugins) used for client-side validation." }, { "name": "Variables", "description": "List all APISIX built-in variables available for use in route matching conditions and plugin configurations." }, { "name": "System Settings", "description": "Manage global dashboard settings including SCIM provisioning, SMTP email server configuration, and admin security settings." }, { "name": "Developer Portal Settings", "description": "Configure developer portal access settings, including public visibility and custom domain configuration." }, { "name": "Login Settings", "description": "Configure authentication providers (OIDC, SAML, LDAP, built-in) available for dashboard user login." }, { "name": "System Infos", "description": "Retrieve system information including the API7 EE version, deployment ID, deployment timestamp, license state, and free trial expiration." }, { "name": "Email", "description": "Manage email verification status for user accounts." }, { "name": "Common", "description": "Utility endpoints shared across multiple resource types, such as version checks and resource name lookups." }, { "name": "Provider Portal - DCR Provider", "description": "Manage Dynamic Client Registration (DCR) providers that allow the developer portal to automatically register OAuth clients with identity providers." }, { "name": "Provider Portal - API Product", "description": "Manage API products — curated bundles of APIs exposed through the developer portal for external developer consumption." }, { "name": "Provider Portal - Portal Instance", "description": "Manage developer portal instances, including their configuration, custom domains, and appearance settings." }, { "name": "Provider Portal - Portal Token", "description": "Manage access tokens for authenticating developer portal API requests." }, { "name": "Developer", "description": "Manage developer accounts registered through the developer portal, including invitations and access control." }, { "name": "Approval", "description": "Manage approval workflows for developer subscription requests to API products." }, { "name": "AI Gateway Group", "description": "Manage AI Gateway groups — logical clusters of AISIX AI Gateway instances. Each group shares the same control plane configuration." }, { "name": "AI Gateway Instance", "description": "View and manage individual AISIX AI Gateway nodes running within an AI Gateway group. Monitor instance health and connection status." } ], "paths": { "/apisix/admin/services": { "post": { "tags": [ "Published Service" ], "summary": "Create a published service on a gateway group", "operationId": "createPublishedService", "description": "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.\n**Required IAM Permission:** Action `gateway:CreatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/*`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "oneOf": [ { "title": "HTTP", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "http" ] }, "hosts": { "type": "array", "description": "The hosts of the service to accept incoming requests.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "path_prefix": { "maxLength": 4096, "minLength": 1, "pattern": "^/", "type": "string", "description": "The listening path prefix of the service.", "example": "/test" }, "strip_path_prefix": { "type": "boolean", "default": true, "description": "If true, strip the path prefix when proxying the request to the upstream." }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "upstream": { "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] } } } ] }, { "title": "Stream", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of service. `stream` corresponds to L4 service.", "enum": [ "stream" ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "upstream": { "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } } } ] } ] }, { "type": "object", "properties": { "status": { "default": 1, "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] } } } ] } } } }, "responses": { "200": { "description": "Service template created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Published Service" ], "summary": "List all published services on a gateway group", "operationId": "listPublishedServices", "description": "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.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "description": "Index to order the services by.", "in": "query", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "last_published", "name" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "unhealthy_nodes", "description": "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.", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "unhealthy_nodes_exists", "no_unhealthy_nodes" ] } } }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "hosts", "in": "query", "schema": { "type": "array", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } }, { "name": "type", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "http", "stream" ] } } }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of service templates.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of services.", "items": { "allOf": [ { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer", "minimum": 0 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/services/{service_id}": { "get": { "tags": [ "Published Service" ], "summary": "Get a published service on a gateway group", "operationId": "getPublishedService", "description": "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.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the service template.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Published Service" ], "summary": "Update a published service without publishing", "operationId": "putPublishedService", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "oneOf": [ { "title": "HTTP", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "http" ] }, "hosts": { "type": "array", "description": "The hosts of the service to accept incoming requests.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "path_prefix": { "maxLength": 4096, "minLength": 1, "pattern": "^/", "type": "string", "description": "The listening path prefix of the service.", "example": "/test" }, "strip_path_prefix": { "type": "boolean", "default": true, "description": "If true, strip the path prefix when proxying the request to the upstream." }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "upstream": { "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] } } } ] }, { "title": "Stream", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Type of service. `stream` corresponds to L4 service.", "enum": [ "stream" ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "upstream": { "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } } } ] } ] }, { "type": "object", "properties": { "status": { "default": 1, "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] } } } ] } } } }, "responses": { "200": { "description": "Service template updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Published Service" ], "summary": "Patch a published service on a gateway group", "operationId": "patchPublishedService", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Service template updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Published Service" ], "summary": "Delete a published service on a gateway group", "operationId": "deletePublishedService", "description": "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.\n**Required IAM Permission:** Action `gateway:DeletePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/services/{service_id}/upstreams": { "post": { "tags": [ "Published Service" ], "summary": "Create a upstream in a published service on a gateway group", "operationId": "createPublishedServiceUpstream", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "HTTP Upstream", "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, { "title": "Stream Upstream", "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } ] } } } }, "responses": { "200": { "description": "Upstream configuration created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The upstream model.", "allOf": [ { "oneOf": [ { "title": "HTTP Upstream", "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, { "title": "Stream Upstream", "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "apisix_service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Published Service" ], "summary": "List all upstreams in a published service on a gateway group", "operationId": "listPublishedServiceUpstreams", "description": "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.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at" ] } }, { "name": "direction", "in": "query", "schema": { "type": "string", "default": "asc", "enum": [ "asc" ] }, "description": "Order to list the routes by. The sorting index follows the configuration of `order_by`." }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of upstream configurations.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of upstream configurations.", "items": { "description": "The upstream model.", "allOf": [ { "oneOf": [ { "title": "HTTP Upstream", "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, { "title": "Stream Upstream", "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "apisix_service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/services/{service_id}/upstreams/{upstream_id}": { "get": { "tags": [ "Published Service" ], "summary": "Get a upstream in a published service on a gateway group", "operationId": "getPublishedServiceUpstream", "description": "Get one upstream in a published service through an APISIX Admin API compatible endpoint under `/apisix/admin/`. The response uses APISIX-style upstream structure.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "upstream_id", "description": "The unique identifier of the upstream.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the upstream configuration.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The upstream model.", "allOf": [ { "oneOf": [ { "title": "HTTP Upstream", "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, { "title": "Stream Upstream", "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "apisix_service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Published Service" ], "summary": "Update a upstream in a published service on a gateway group", "operationId": "putPublishedServiceUpstream", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "upstream_id", "description": "The unique identifier of the upstream.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "HTTP Upstream", "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, { "title": "Stream Upstream", "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } ] } } } }, "responses": { "200": { "description": "Upstream configuration updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The upstream model.", "allOf": [ { "oneOf": [ { "title": "HTTP Upstream", "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, { "title": "Stream Upstream", "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "apisix_service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Published Service" ], "summary": "Patch a upstream in a published service on a gateway group", "operationId": "patchPublishedServiceUpstream", "description": "Partially update an upstream in a published service via JSON Patch (RFC 6902) through an APISIX Admin API compatible endpoint under `/apisix/admin/`.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "upstream_id", "description": "The unique identifier of the upstream.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Upstream configuration updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The upstream model.", "allOf": [ { "oneOf": [ { "title": "HTTP Upstream", "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, { "title": "Stream Upstream", "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "apisix_service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Published Service" ], "summary": "Delete a upstream in a published service on a gateway group", "operationId": "deletePublishedServiceUpstream", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "upstream_id", "description": "The unique identifier of the upstream.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/services/template": { "post": { "tags": [ "Service Template" ], "summary": "Create a service template", "operationId": "createServiceTemplate", "description": "IAM Action: `gateway:CreateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/*`", "requestBody": { "content": { "application/json": { "schema": { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] } } } }, "responses": { "200": { "description": "Service template created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Service Template" ], "summary": "Get all service templates", "operationId": "listServiceTemplates", "description": "IAM Action: `gateway:GetServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "description": "Index to order the services by.", "in": "query", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "last_published", "name" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } }, { "name": "last_publish_start_at", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "last_publish_end_at", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "type", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "http", "stream" ], "example": "http" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of service templates.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of services.", "items": { "allOf": [ { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer", "minimum": 0 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/services/template/{service_template_id}": { "get": { "tags": [ "Service Template" ], "summary": "Get a service template by ID", "operationId": "getServiceTemplate", "description": "IAM Action: `gateway:GetServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the service template.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Service Template" ], "summary": "Update a service template by ID", "operationId": "putServiceTemplate", "description": "IAM Action: `gateway:UpdateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] } } } }, "responses": { "200": { "description": "Service template updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Service Template" ], "summary": "Patch a service template by ID", "operationId": "patchServiceTemplate", "description": "IAM Action: `gateway:UpdateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "in": "query", "name": "dry-run", "schema": { "type": "string", "enum": [ "all" ] }, "description": "When specified, run the operation in dry-run mode." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Service template updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Service Template" ], "summary": "Delete a service template", "operationId": "deleteServiceTemplate", "description": "IAM Action: `gateway:DeleteServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/services/template/{service_template_id}/oas": { "get": { "tags": [ "Service Template" ], "summary": "Get the OpenAPI Specification of a service template", "operationId": "getServiceTemplateOAS", "description": "IAM Action: `gateway:GetServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the OpenAPI specification for the service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI spec of the service.", "example": "Raw OpenAPI spec" }, "api_count": { "type": "integer", "description": "The number of APIs in the service.", "example": 10 }, "api_desc": { "type": "string", "description": "The description of the OAS.", "example": "OAS description." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Service Template" ], "summary": "Update the OpenAPI Specification of a service template", "operationId": "putServiceTemplateOAS", "description": "IAM Action: `gateway:UpdateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI spec of the service.", "example": "Raw OpenAPI spec" } } } } } }, "responses": { "200": { "description": "Successfully retrieved the OpenAPI specification for the service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI spec of the service.", "example": "Raw OpenAPI spec" }, "api_count": { "type": "integer", "description": "The number of APIs in the service.", "example": 10 }, "api_desc": { "type": "string", "description": "The description of the OAS.", "example": "OAS description." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/secret_providers": { "get": { "tags": [ "Secret Provider" ], "summary": "List all secret providers on a gateway group", "operationId": "listSecretProviders", "description": "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.\n**Required IAM Permission:** Action `gateway:GetSecretProvider`, Resource `arn:api7:gateway:gatewaygroup/%s/secret_provider/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Get all secrets.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "Array of Secrets.", "items": { "description": "secret with management fields", "allOf": [ { "allOf": [ { "oneOf": [ { "title": "Vault", "description": "HashiCorp Vault configurations when Vault is the secret provider.", "type": "object", "required": [ "uri", "prefix", "token" ], "properties": { "uri": { "description": "Vault endpoint.", "example": "http://10.42.17.8:8200", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "prefix": { "type": "string", "description": "Vault prefix to access secrets.", "example": "kv/apisix" }, "token": { "type": "string", "description": "Vault token.", "example": "apisix-quickstart-vault-token" }, "namespace": { "type": "string", "description": "Vault namespace.", "example": "apisix" }, "kv_version": { "type": "string", "description": "Vault KV secrets engine version.", "enum": [ "kv-v1" ], "default": "kv-v1" }, "authentication_method": { "type": "string", "description": "Authentication method.", "enum": [ "token" ], "default": "token" } } }, { "title": "AWS Secret", "description": "AWS Secret configurations when AWS Secret is the secret provider.", "type": "object", "required": [ "access_key_id", "secret_access_key" ], "properties": { "access_key_id": { "description": "AWS access key ID.", "type": "string" }, "secret_access_key": { "description": "AWS secret access key.", "type": "string" }, "session_token": { "description": "AWS session token.", "type": "string" }, "region": { "type": "string", "description": "AWS region.", "default": "us-east-1" }, "endpoint_url": { "description": "AWS endpoint.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" } } }, { "type": "object", "description": "Kubernetes Secret configurations when Kubernetes Secret is the secret provider.", "properties": { "apiserver_addr": { "description": "Kubernetes API server Address.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "token": { "description": "Service account token for Kubernetes API authentication", "type": "string", "minLength": 1 }, "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "minLength": 1 } }, "oneOf": [ { "title": "Kubernetes Secret (Token)", "required": [ "apiserver_addr", "token" ] }, { "title": "Kubernetes Secret (Token File)", "required": [ "apiserver_addr", "token_file" ] } ] } ] }, { "type": "object", "properties": { "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] }, { "type": "object", "properties": { "id": { "description": "Secret ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "secret_provider": { "type": "string", "description": "Type of secret manager.", "enum": [ "vault", "aws", "kubernetes" ], "example": "vault" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/secret_providers/{secret_provider}/{secret_provider_id}": { "get": { "tags": [ "Secret Provider" ], "summary": "Get a secret provider on a gateway group", "operationId": "getSecretProvider", "description": "Retrieve details of one secret provider integration in the gateway group, including provider-specific connection settings.\n**Required IAM Permission:** Action `gateway:GetSecretProvider`, Resource `arn:api7:gateway:gatewaygroup/%s/secret_provider/%s`", "parameters": [ { "name": "secret_provider", "description": "Secret provider.", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "vault", "aws", "kubernetes" ] } }, { "name": "secret_provider_id", "description": "Secret provider ID.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Get a secret by ID.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "secret with management fields", "allOf": [ { "allOf": [ { "oneOf": [ { "title": "Vault", "description": "HashiCorp Vault configurations when Vault is the secret provider.", "type": "object", "required": [ "uri", "prefix", "token" ], "properties": { "uri": { "description": "Vault endpoint.", "example": "http://10.42.17.8:8200", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "prefix": { "type": "string", "description": "Vault prefix to access secrets.", "example": "kv/apisix" }, "token": { "type": "string", "description": "Vault token.", "example": "apisix-quickstart-vault-token" }, "namespace": { "type": "string", "description": "Vault namespace.", "example": "apisix" }, "kv_version": { "type": "string", "description": "Vault KV secrets engine version.", "enum": [ "kv-v1" ], "default": "kv-v1" }, "authentication_method": { "type": "string", "description": "Authentication method.", "enum": [ "token" ], "default": "token" } } }, { "title": "AWS Secret", "description": "AWS Secret configurations when AWS Secret is the secret provider.", "type": "object", "required": [ "access_key_id", "secret_access_key" ], "properties": { "access_key_id": { "description": "AWS access key ID.", "type": "string" }, "secret_access_key": { "description": "AWS secret access key.", "type": "string" }, "session_token": { "description": "AWS session token.", "type": "string" }, "region": { "type": "string", "description": "AWS region.", "default": "us-east-1" }, "endpoint_url": { "description": "AWS endpoint.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" } } }, { "type": "object", "description": "Kubernetes Secret configurations when Kubernetes Secret is the secret provider.", "properties": { "apiserver_addr": { "description": "Kubernetes API server Address.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "token": { "description": "Service account token for Kubernetes API authentication", "type": "string", "minLength": 1 }, "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "minLength": 1 } }, "oneOf": [ { "title": "Kubernetes Secret (Token)", "required": [ "apiserver_addr", "token" ] }, { "title": "Kubernetes Secret (Token File)", "required": [ "apiserver_addr", "token_file" ] } ] } ] }, { "type": "object", "properties": { "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] }, { "type": "object", "properties": { "id": { "description": "Secret ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "secret_provider": { "type": "string", "description": "Type of secret manager.", "enum": [ "vault", "aws", "kubernetes" ], "example": "vault" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Secret Provider" ], "summary": "Delete a secret provider on a gateway group", "operationId": "deleteSecretProvider", "description": "Delete a secret provider integration from the gateway group. Ensure no plugin or resource still references secrets from this provider before removal.\n**Required IAM Permission:** Action `gateway:DeleteSecretProvider`, Resource `arn:api7:gateway:gatewaygroup/%s/secret_provider/%s`", "parameters": [ { "name": "secret_provider", "description": "Secret provider.", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "vault", "aws", "kubernetes" ] } }, { "name": "secret_provider_id", "description": "Secret provider ID.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Secret Provider" ], "summary": "Update a secret provider on a gateway group", "operationId": "putSecretProvider", "description": "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.\n**Required IAM Permission:** Action `gateway:PutSecretProvider`, Resource `arn:api7:gateway:gatewaygroup/%s/secret_provider/%s`", "parameters": [ { "name": "secret_provider", "description": "Secret provider.", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "vault", "aws", "kubernetes" ] } }, { "name": "secret_provider_id", "description": "Secret provider ID.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "oneOf": [ { "title": "Vault", "description": "HashiCorp Vault configurations when Vault is the secret provider.", "type": "object", "required": [ "uri", "prefix", "token" ], "properties": { "uri": { "description": "Vault endpoint.", "example": "http://10.42.17.8:8200", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "prefix": { "type": "string", "description": "Vault prefix to access secrets.", "example": "kv/apisix" }, "token": { "type": "string", "description": "Vault token.", "example": "apisix-quickstart-vault-token" }, "namespace": { "type": "string", "description": "Vault namespace.", "example": "apisix" }, "kv_version": { "type": "string", "description": "Vault KV secrets engine version.", "enum": [ "kv-v1" ], "default": "kv-v1" }, "authentication_method": { "type": "string", "description": "Authentication method.", "enum": [ "token" ], "default": "token" } } }, { "title": "AWS Secret", "description": "AWS Secret configurations when AWS Secret is the secret provider.", "type": "object", "required": [ "access_key_id", "secret_access_key" ], "properties": { "access_key_id": { "description": "AWS access key ID.", "type": "string" }, "secret_access_key": { "description": "AWS secret access key.", "type": "string" }, "session_token": { "description": "AWS session token.", "type": "string" }, "region": { "type": "string", "description": "AWS region.", "default": "us-east-1" }, "endpoint_url": { "description": "AWS endpoint.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" } } }, { "type": "object", "description": "Kubernetes Secret configurations when Kubernetes Secret is the secret provider.", "properties": { "apiserver_addr": { "description": "Kubernetes API server Address.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "token": { "description": "Service account token for Kubernetes API authentication", "type": "string", "minLength": 1 }, "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "minLength": 1 } }, "oneOf": [ { "title": "Kubernetes Secret (Token)", "required": [ "apiserver_addr", "token" ] }, { "title": "Kubernetes Secret (Token File)", "required": [ "apiserver_addr", "token_file" ] } ] } ] }, { "type": "object", "properties": { "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] } } } }, "responses": { "200": { "description": "Update a secret by ID.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "secret with management fields", "allOf": [ { "allOf": [ { "oneOf": [ { "title": "Vault", "description": "HashiCorp Vault configurations when Vault is the secret provider.", "type": "object", "required": [ "uri", "prefix", "token" ], "properties": { "uri": { "description": "Vault endpoint.", "example": "http://10.42.17.8:8200", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "prefix": { "type": "string", "description": "Vault prefix to access secrets.", "example": "kv/apisix" }, "token": { "type": "string", "description": "Vault token.", "example": "apisix-quickstart-vault-token" }, "namespace": { "type": "string", "description": "Vault namespace.", "example": "apisix" }, "kv_version": { "type": "string", "description": "Vault KV secrets engine version.", "enum": [ "kv-v1" ], "default": "kv-v1" }, "authentication_method": { "type": "string", "description": "Authentication method.", "enum": [ "token" ], "default": "token" } } }, { "title": "AWS Secret", "description": "AWS Secret configurations when AWS Secret is the secret provider.", "type": "object", "required": [ "access_key_id", "secret_access_key" ], "properties": { "access_key_id": { "description": "AWS access key ID.", "type": "string" }, "secret_access_key": { "description": "AWS secret access key.", "type": "string" }, "session_token": { "description": "AWS session token.", "type": "string" }, "region": { "type": "string", "description": "AWS region.", "default": "us-east-1" }, "endpoint_url": { "description": "AWS endpoint.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" } } }, { "type": "object", "description": "Kubernetes Secret configurations when Kubernetes Secret is the secret provider.", "properties": { "apiserver_addr": { "description": "Kubernetes API server Address.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "token": { "description": "Service account token for Kubernetes API authentication", "type": "string", "minLength": 1 }, "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "minLength": 1 } }, "oneOf": [ { "title": "Kubernetes Secret (Token)", "required": [ "apiserver_addr", "token" ] }, { "title": "Kubernetes Secret (Token File)", "required": [ "apiserver_addr", "token_file" ] } ] } ] }, { "type": "object", "properties": { "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] }, { "type": "object", "properties": { "id": { "description": "Secret ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "secret_provider": { "type": "string", "description": "Type of secret manager.", "enum": [ "vault", "aws", "kubernetes" ], "example": "vault" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/protos": { "get": { "tags": [ "Proto" ], "summary": "List all protos on a gateway group", "operationId": "listProtos", "description": "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.\n**Required IAM Permission:** Action `gateway:GetProto`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of protobuf definitions.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of protos.", "items": { "description": "The proto with management fields.", "allOf": [ { "description": "The proto description.", "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The protobuf content.", "minLength": 1, "maxLength": 1048576, "example": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "post": { "tags": [ "Proto" ], "summary": "Create a proto on a gateway group", "operationId": "createProto", "description": "Upload a new .proto definition to the gateway group for gRPC transcoding scenarios. Ensure package and service definitions align with upstream gRPC services.\n**Required IAM Permission:** Action `gateway:CreateProto`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The proto description.", "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The protobuf content.", "minLength": 1, "maxLength": 1048576, "example": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Protobuf definition created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The proto with management fields.", "allOf": [ { "description": "The proto description.", "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The protobuf content.", "minLength": 1, "maxLength": 1048576, "example": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/protos/{proto_id}": { "get": { "tags": [ "Proto" ], "summary": "Get a proto on a gateway group", "operationId": "getProto", "description": "Retrieve one proto definition from the gateway group, including its current content and metadata.\n**Required IAM Permission:** Action `gateway:GetProto`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "proto_id", "description": "The unique identifier of the proto.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the protobuf definition.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The proto with management fields.", "allOf": [ { "description": "The proto description.", "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The protobuf content.", "minLength": 1, "maxLength": 1048576, "example": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Proto" ], "summary": "Update a proto on a gateway group", "operationId": "putProto", "description": "Replace an existing proto definition in the gateway group. After updates, verify dependent gRPC-transcode routes still match the revised service and method signatures.\n**Required IAM Permission:** Action `gateway:UpdateProto`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "proto_id", "description": "The unique identifier of the proto.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The proto description.", "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The protobuf content.", "minLength": 1, "maxLength": 1048576, "example": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Protobuf definition updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The proto with management fields.", "allOf": [ { "description": "The proto description.", "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The protobuf content.", "minLength": 1, "maxLength": 1048576, "example": "syntax = \"proto3\";\n\nmessage Person {\n string name = 1;\n int32 id = 2;\n string email = 3;\n}\n" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Proto" ], "summary": "Delete a proto on a gateway group", "operationId": "deleteProto", "description": "Delete a proto definition from the gateway group. Check for any gRPC-transcode plugin configurations that still reference this proto before deletion.\n**Required IAM Permission:** Action `gateway:DeleteProto`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "proto_id", "description": "The unique identifier of the proto.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/export/services/template": { "post": { "tags": [ "Service Template" ], "summary": "Generate an OpenAPI specification from service templates", "operationId": "generateOpenAPISpec", "description": "Export service template definitions as an OpenAPI 3.0 specification document. Use this endpoint to share, version, or migrate API definitions between environments.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "scope", "description": "Scope of the service.", "in": "query", "schema": { "type": "string", "enum": [ "partial", "all" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "info" ], "properties": { "service_ids": { "type": "array", "description": "The service ID list.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "info": { "type": "object", "description": "API metadata.", "properties": { "title": { "type": "string", "description": "Title of the exported API definition.", "example": "Swagger Petstore" }, "version": { "type": "string", "description": "Version of the exported API definition.", "example": "3.0.1" }, "description": { "type": "string", "description": "Description of the exported API definition.", "example": "API description." } }, "required": [ "title", "version" ] }, "servers": { "type": "array", "description": "An array of one or more base servers in the exported API definition.", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Server URL.", "example": "http://localhost:8080" }, "description": { "type": "string", "description": "Server description.", "example": "Localhost test server." } } } } } } } } }, "responses": { "200": { "description": "Successfully exported the service as an OpenAPI specification.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "openapi": { "type": "string", "description": "The OpenAPI version.", "default": "3.0.1" }, "info": { "type": "object", "description": "API metadata.", "properties": { "title": { "type": "string", "description": "Title of the exported API definition.", "example": "Swagger Petstore" }, "version": { "type": "string", "description": "Version of the exported API definition.", "example": "3.0.1" }, "description": { "type": "string", "description": "Description of the exported API definition.", "example": "API description." } }, "required": [ "title", "version" ] }, "servers": { "type": "array", "description": "An array of one or more base servers in the exported API definition.", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Server URL.", "example": "http://localhost:8080" }, "description": { "type": "string", "description": "Server description.", "example": "Localhost test server." } } } }, "paths": { "type": "object", "description": "Endpoint paths and their operations.", "example": { "/anything": { "delete": { "responses": { "default": { "description": "" } }, "tags": [ "httpbin" ] }, "get": { "responses": { "default": { "description": "" } }, "tags": [ "httpbin" ] }, "patch": { "responses": { "default": { "description": "" } }, "tags": [ "httpbin" ] }, "post": { "responses": { "default": { "description": "" } }, "tags": [ "httpbin" ] }, "put": { "responses": { "default": { "description": "" } }, "tags": [ "httpbin" ] }, "trace": { "responses": { "default": { "description": "" } }, "tags": [ "httpbin" ] } } }, "additionalProperties": { "type": "object", "properties": { "get": { "type": "object", "properties": { "responses": { "type": "object" } } }, "put": { "type": "object", "properties": { "responses": { "type": "object" } } }, "post": { "type": "object", "properties": { "responses": { "type": "object" } } }, "delete": { "type": "object", "properties": { "responses": { "type": "object" } } }, "options": { "type": "object", "properties": { "responses": { "type": "object" } } }, "head": { "type": "object", "properties": { "responses": { "type": "object" } } }, "patch": { "type": "object", "properties": { "responses": { "type": "object" } } } } } } }, "required": [ "openapi", "info", "paths" ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/import/services/template": { "post": { "tags": [ "Service Template" ], "summary": "Import service template based on OpenAPI Specification", "operationId": "importServiceTemplateOpenAPISpec", "description": "Import an OpenAPI specification and create service template resources from it. This operation translates API paths and components into template-level gateway configuration.\n\n**Required IAM Permission:** Action `gateway:CreateServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/*`", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "enum": [ "http" ], "default": "http", "description": "Type of service." } } }, { "type": "object", "properties": { "routes": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Route configurations.", "items": { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } } } } } ] } } } }, "responses": { "200": { "description": "Service template imported from OpenAPI specification successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The service with management fields.", "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "last_published": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "published_gateway_groups_count": { "type": "integer" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "routes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/import/services": { "post": { "tags": [ "Published Service" ], "summary": "Import services based on OpenAPI Specification", "operationId": "importServiceOpenAPISpec", "description": "Import an OpenAPI specification directly into published services for a gateway group. This operation creates runtime service resources scoped to the target gateway group.\n\n**Required IAM Permission:** Action `gateway:CreatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/*`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "enum": [ "http" ], "default": "http", "description": "Type of service." } } }, { "type": "object", "properties": { "routes": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Route configurations.", "items": { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } } } } } ] } } } }, "responses": { "200": { "description": "Published service imported from OpenAPI specification successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "unhealthy_nodes_count": { "type": "integer", "description": "Unhealthy nodes count.", "example": 0 }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/openapi/convert": { "put": { "tags": [ "Service Template", "Published Service" ], "summary": "Convert OpenAPI Specification to service and route resources", "description": "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.", "operationId": "convertOpenAPISpec", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "raw_openapi" ], "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI content.", "example": "Raw OpenAPI spec" } } } } } }, "responses": { "200": { "description": "Successfully converted the OpenAPI specification to an API7 service definition.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The service description.", "type": "object", "required": [ "name" ], "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "routes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] } } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/license": { "get": { "tags": [ "License" ], "summary": "Get API7 Enterprise license details", "operationId": "getLicense", "description": "Retrieve current API7 Enterprise license information, including validity and licensed capabilities. Use this endpoint to inspect license status for operations and troubleshooting.", "responses": { "200": { "description": "Successfully retrieved the current license information.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The license object.", "allOf": [ { "type": "object", "properties": { "customer": { "type": "string", "description": "The customer name.", "example": "API7" }, "effective_at": { "type": "integer", "format": "int32", "description": "The timestamp when the license becomes effective.", "example": 1654012800 }, "expired_at": { "type": "integer", "format": "int32", "description": "The timestamp when the license expires.", "example": 1717171200 }, "max_dp_cores": { "type": "integer", "description": "The maximum number of DP cores.", "example": 100 }, "feature_list": { "type": "array", "description": "An array of licensed features.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "API7 Gateway", "API7 Portal" ] } }, "deployment_id": { "type": "string", "description": "A unique identifier that is automatically generated with each deployment of API7 Enterprise.", "example": "d1e1ea2b-2cff-4c38-b57e-408e1dffec52" }, "free_trial": { "type": "boolean", "description": "If true, the license is for free trial only." }, "is_test_env": { "type": "boolean", "description": "If true, license is for test environment." }, "issuance_date": { "type": "integer", "format": "int32", "description": "The license issuance timestamp.", "example": 1625769798 }, "ai_gateway": { "type": "object", "description": "AI Gateway authorization status.", "properties": { "status": { "type": "string", "enum": [ "not_authorized", "not_effective", "normal", "expired" ], "description": "The AI Gateway authorization status:\n- not_authorized: AI Gateway is not included in the license.\n- not_effective: AI Gateway license has not yet taken effect.\n- normal: AI Gateway is authorized and active.\n- expired: AI Gateway license has expired. Existing configurations remain active, but modifications are not allowed.\n" }, "effective_at": { "type": "integer", "format": "int32", "description": "The timestamp when the AI Gateway license becomes effective.", "example": 1654012800 }, "expired_at": { "type": "integer", "format": "int32", "description": "The timestamp when the AI Gateway license expires.", "example": 1717171200 } } } } }, { "type": "object", "properties": { "runtime": { "type": "object", "properties": { "status": { "type": "string", "default": "normal", "example": "dp_core_exceeded", "enum": [ "normal", "dp_core_exceeded", "dp_core_exceeded_restricted" ], "description": "The license runtime status, which can be either normal or dp_core_exceeded or dp_core_exceeded_restricted." }, "dp_core_exceeded_start_at": { "type": "integer", "format": "int32", "description": "The start time when the number of DP cores exceeds the maximum number of DP cores of the license (buffering state).", "example": 1654012700 }, "dp_core_exceeded_end_at": { "type": "integer", "format": "int32", "description": "The end time when the number of DP cores exceeds the maximum number of DP cores of the license (buffering state). In this case, API usage will be restricted.", "example": 1654012750 }, "max_dp_cores": { "type": "integer", "format": "int32", "description": "The highest number of cores during the buffering period, which is 0 in normal conditions.", "example": 100 } } } } }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "normal", "expired" ], "description": "The license status, which can be either normal or expired." } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "License" ], "summary": "Import or update the API7 Enterprise license", "operationId": "updateLicense", "description": "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.\n\n**Required IAM Permission:** Action `iam:UpdateLicense`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "in": "query", "name": "dry-run", "schema": { "type": "string", "enum": [ "all" ] }, "description": "When specified, run the operation in dry-run mode." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Encoded license data.", "example": "“xxxx1N-tNaTpttX-NjOdXjyg\"" } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "License imported successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The license object.", "type": "object", "properties": { "customer": { "type": "string", "description": "The customer name.", "example": "API7" }, "effective_at": { "type": "integer", "format": "int32", "description": "The timestamp when the license becomes effective.", "example": 1654012800 }, "expired_at": { "type": "integer", "format": "int32", "description": "The timestamp when the license expires.", "example": 1717171200 }, "max_dp_cores": { "type": "integer", "description": "The maximum number of DP cores.", "example": 100 }, "feature_list": { "type": "array", "description": "An array of licensed features.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "API7 Gateway", "API7 Portal" ] } }, "deployment_id": { "type": "string", "description": "A unique identifier that is automatically generated with each deployment of API7 Enterprise.", "example": "d1e1ea2b-2cff-4c38-b57e-408e1dffec52" }, "free_trial": { "type": "boolean", "description": "If true, the license is for free trial only." }, "is_test_env": { "type": "boolean", "description": "If true, license is for test environment." }, "issuance_date": { "type": "integer", "format": "int32", "description": "The license issuance timestamp.", "example": 1625769798 }, "ai_gateway": { "type": "object", "description": "AI Gateway authorization status.", "properties": { "status": { "type": "string", "enum": [ "not_authorized", "not_effective", "normal", "expired" ], "description": "The AI Gateway authorization status:\n- not_authorized: AI Gateway is not included in the license.\n- not_effective: AI Gateway license has not yet taken effect.\n- normal: AI Gateway is authorized and active.\n- expired: AI Gateway license has expired. Existing configurations remain active, but modifications are not allowed.\n" }, "effective_at": { "type": "integer", "format": "int32", "description": "The timestamp when the AI Gateway license becomes effective.", "example": 1654012800 }, "expired_at": { "type": "integer", "format": "int32", "description": "The timestamp when the AI Gateway license expires.", "example": 1717171200 } } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/routes": { "post": { "tags": [ "Route", "Published Service" ], "summary": "Create a route in a published service on a gateway group", "operationId": "createPublishedServiceRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The route with the service ID.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "required": [ "service_id" ], "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } }, "responses": { "200": { "description": "Route created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Route", "Published Service" ], "summary": "List all routes in a published service", "operationId": "listPublishedServiceRoutes", "description": "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.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "query", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of routes.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of routes.", "items": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/routes/{route_id}": { "get": { "tags": [ "Route", "Published Service" ], "summary": "Get a route in a published service on a gateway group", "operationId": "getPublishedServiceRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "route_id", "description": "The unique identifier of the published route.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Route", "Published Service" ], "summary": "Update a route in a published service on a gateway group", "operationId": "putPublishedServiceRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "route_id", "description": "The unique identifier of the published route.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The route with the service ID.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "required": [ "service_id" ], "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } }, "responses": { "200": { "description": "Route updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Route", "Published Service" ], "summary": "Patch a route in a published service on a gateway group", "operationId": "patchPublishedServiceRoute", "description": "Partially update a route in a published service via JSON Patch (RFC 6902) through an APISIX Admin API compatible endpoint under `/apisix/admin/`.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "route_id", "description": "The unique identifier of the published route.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Route updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Route", "Published Service" ], "summary": "Delete a route in a published service on a gateway group", "operationId": "deletePublishedServiceRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "route_id", "description": "The unique identifier of the published route.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "401": { "description": "Unauthorized — Authentication is required. Provide a valid API key via the X-API-KEY header or use Basic Auth credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/routes/template": { "post": { "tags": [ "Service Template", "Route" ], "summary": "Create a route in a service template", "operationId": "createServiceTemplateRoute", "description": "IAM Action: `gateway:UpdateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "requestBody": { "content": { "application/json": { "schema": { "description": "The route template payload.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } }, "required": [ "service_id" ] } ] } } } }, "responses": { "200": { "description": "Route created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Service Template", "Route" ], "summary": "Get all routes in a service template", "operationId": "listServiceTemplateRoutes", "description": "IAM Action: `gateway:GetServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the service template.", "in": "query", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of routes.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of routes.", "items": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/routes/template/{route_template_id}": { "get": { "tags": [ "Service Template", "Route" ], "summary": "Get a route in all service templates", "operationId": "getServiceTemplateRoute", "description": "IAM Action: `gateway:GetServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "route_template_id", "description": "The unique identifier of the route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Service Template" ], "summary": "Update a route in service template", "operationId": "putServiceTemplateRoute", "description": "IAM Action: `gateway:UpdateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "route_template_id", "description": "The unique identifier of the route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The route with the optional service ID.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } }, "responses": { "200": { "description": "Route updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Service Template", "Route" ], "summary": "Patch a route in service template", "operationId": "patchServiceTemplateRoute", "description": "IAM Action: `gateway:UpdateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "route_template_id", "description": "The unique identifier of the route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Route updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Service Template", "Route" ], "summary": "Delete a route in service template", "operationId": "deleteServiceTemplateRoute", "description": "IAM Action: `gateway:UpdateServiceTemplate`, Resource: `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "route_template_id", "description": "The unique identifier of the route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "401": { "description": "Unauthorized — Authentication is required. Provide a valid API key via the X-API-KEY header or use Basic Auth credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/stream_routes": { "post": { "tags": [ "Stream Route", "Published Service" ], "summary": "Create a stream route in a published service on a gateway group", "operationId": "createPublishedServiceStreamRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The stream route with the service ID.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "required": [ "service_id" ], "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Stream Route", "Published Service" ], "summary": "List all stream routes in a published service on a gateway group", "operationId": "listPublishedServiceStreamRoutes", "description": "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.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the published service.", "in": "query", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of stream routes.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of routes.", "items": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/stream_routes/{stream_route_id}": { "get": { "tags": [ "Stream Route", "Published Service" ], "summary": "Get a stream route in a published service on a gateway group", "operationId": "getPublishedServiceStreamRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "stream_route_id", "description": "The unique identifier of the published stream route.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "with_publish_info", "description": "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.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved or modified the stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Stream Route", "Published Service" ], "summary": "Update a stream route in a published service on a gateway group", "operationId": "putPublishedServiceStreamRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "stream_route_id", "description": "The unique identifier of the published stream route.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The stream route with the service ID.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "required": [ "service_id" ], "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Stream Route", "Published Service" ], "summary": "Delete a stream route in a published service on a gateway group", "operationId": "deletePublishedServiceStreamRoute", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "stream_route_id", "description": "The unique identifier of the published stream route.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/configs/validate": { "post": { "tags": [ "Configuration" ], "summary": "Validate batch configuration", "operationId": "validateConfigs", "description": "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.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object" } }, "services": { "type": "array", "items": { "type": "object" } }, "consumers": { "type": "array", "items": { "type": "object" } }, "upstreams": { "type": "array", "items": { "type": "object" } }, "ssls": { "type": "array", "items": { "type": "object" } }, "global_rules": { "type": "array", "items": { "type": "object" } }, "stream_routes": { "type": "array", "items": { "type": "object" } }, "plugin_metadata": { "type": "array", "items": { "type": "object" } }, "plugin_configs": { "type": "array", "items": { "type": "object" } }, "consumer_groups": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/stream_routes/template": { "post": { "tags": [ "Stream Route", "Service Template" ], "summary": "Create a stream route in a service template", "operationId": "createServiceTemplateStreamRoute", "description": "Create a Layer 4 stream route in the service template to route TCP or UDP traffic for non-HTTP protocols. Define matching rules and upstream behavior to control how connection-level traffic is proxied.\n**Required IAM Permission:** Action `gateway:UpdateServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "requestBody": { "content": { "application/json": { "schema": { "description": "The stream route template payload.", "allOf": [ { "description": "The stream route template.", "type": "object", "required": [ "name" ], "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Stream Route", "Service Template" ], "summary": "List all stream routes in a service template", "operationId": "listServiceTemplateStreamRoutes", "description": "List stream routes defined in the service template for TCP/UDP traffic proxying. Use pagination and filters to inspect existing Layer 4 routing policies.\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_id", "description": "The unique identifier of the service template.", "in": "query", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of stream routes.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of routes.", "items": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/stream_routes/template/{stream_route_template_id}": { "get": { "tags": [ "Stream Route", "Service Template" ], "summary": "Get a stream route in a service template", "operationId": "getServiceTemplateStreamRoute", "description": "Retrieve a specific stream route from the service template, including its matching and forwarding configuration for non-HTTP traffic.\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "stream_route_template_id", "description": "The unique identifier of the stream route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved or modified the stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Stream Route", "Service Template" ], "summary": "Update a stream route in a service template", "operationId": "putServiceTemplateStreamRoute", "description": "Replace a stream route configuration in the service template. Updates may immediately affect active TCP/UDP connection routing behavior.\n**Required IAM Permission:** Action `gateway:UpdateServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "stream_route_template_id", "description": "The unique identifier of the stream route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The stream route with the optional service ID.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The stream route with management fields.", "allOf": [ { "description": "The stream route description.", "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Stream Route", "Service Template" ], "summary": "Delete a stream route in a service template", "operationId": "deleteServiceTemplateStreamRoute", "description": "Delete a stream route from the service template to stop applying that Layer 4 routing rule. Confirm there is an alternative path for affected TCP/UDP traffic before deletion.\n**Required IAM Permission:** Action `gateway:UpdateServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "stream_route_template_id", "description": "The unique identifier of the stream route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/ssls": { "post": { "deprecated": true, "tags": [ "SSL" ], "summary": "Create an SSL certificate", "operationId": "createSSL", "description": "IAM Action: `gateway:CreateSSLCertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The SSL certificate description.", "oneOf": [ { "title": "Use Key and Cert", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "required": [ "key", "cert" ], "properties": { "key": { "description": "Private key content or reference to the private key content.", "type": "string", "oneOf": [ { "title": "Private Key Reference", "description": "Path to the private key in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Private Key Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } ] }, "cert": { "description": "Certificate content or reference to the certificate content.", "type": "string", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } } } ] }, { "title": "Use Keys and Certs", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "required": [ "keys", "certs" ], "properties": { "keys": { "description": "An array of private key content or reference to the private key content.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "description": "Private key.", "oneOf": [ { "title": "Private Key Reference", "description": "Path to the private key in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Private Key Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } ] } }, "certs": { "description": "An array of certificate content or reference to the certificate content.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } } } } ] } ] } } } }, "responses": { "200": { "description": "SSL certificate created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The SSL response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } } } }, "get": { "deprecated": true, "tags": [ "SSL" ], "summary": "List all SSL certificates on a gateway group", "operationId": "listSSLs", "description": "IAM Action: `gateway:GetSSLCertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "type", "description": "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.", "in": "query", "required": false, "schema": { "default": "server", "type": "string", "enum": [ "client", "server" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of SSL certificates.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of SSL certificates.", "items": { "description": "The SSL response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/ssls/{ssl_id}": { "get": { "deprecated": true, "tags": [ "SSL" ], "summary": "Get an SSL certificate on a gateway group", "operationId": "getSSL", "description": "IAM Action: `gateway:GetSSLCertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "ssl_id", "description": "The unique identifier of the SSL object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the SSL certificate.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The SSL response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "deprecated": true, "tags": [ "SSL" ], "summary": "Update an SSL certificate on a gateway group", "operationId": "putSSL", "description": "IAM Action: `gateway:UpdateSSLCertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "ssl_id", "description": "The unique identifier of the SSL object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The SSL certificate description.", "oneOf": [ { "title": "Use Key and Cert", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "required": [ "key", "cert" ], "properties": { "key": { "description": "Private key content or reference to the private key content.", "type": "string", "oneOf": [ { "title": "Private Key Reference", "description": "Path to the private key in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Private Key Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } ] }, "cert": { "description": "Certificate content or reference to the certificate content.", "type": "string", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } } } ] }, { "title": "Use Keys and Certs", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "required": [ "keys", "certs" ], "properties": { "keys": { "description": "An array of private key content or reference to the private key content.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "description": "Private key.", "oneOf": [ { "title": "Private Key Reference", "description": "Path to the private key in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Private Key Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } ] } }, "certs": { "description": "An array of certificate content or reference to the certificate content.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } } } } ] } ] } } } }, "responses": { "200": { "description": "SSL certificate updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The SSL response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "snis": { "type": "array", "description": "The SNI list for matching the SSL certificate.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "client": { "description": "Client certificate.", "type": "object", "required": [ "ca" ], "properties": { "ca": { "description": "Client CA certificate in PEM format.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "type": { "type": "string", "description": "Type of certificate. Only support `server` at the moment, which represents certificates used by the Gateway to verify client requests.", "enum": [ "server" ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "deprecated": true, "tags": [ "SSL" ], "summary": "Delete an SSL certificate on a gateway group", "operationId": "deleteSSL", "description": "IAM Action: `gateway:DeleteSSLCertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "ssl_id", "description": "The unique identifier of the SSL object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/certificates": { "post": { "tags": [ "Certificate" ], "summary": "Create a certificate", "operationId": "createCertificate", "description": "Create a TLS server certificate for the gateway group, including the certificate chain and private key used for HTTPS termination.\n**Required IAM Permission:** Action `gateway:CreateCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The certificate description.", "type": "object", "required": [ "key", "cert" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "key": { "type": "string", "description": "Private key.", "oneOf": [ { "title": "Private Key Reference", "description": "Path to the private key in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Private Key Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } ] } } } ] } } } }, "responses": { "200": { "description": "Certificate created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "common_name": { "type": "string", "description": "The common name of the certificate.", "example": "example.com" }, "subject_alt_names": { "type": "array", "description": "The subject alternative names of the certificate.", "items": { "type": "string", "example": "www.example.com" } }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string", "example": "1cf56bfe-7727-4584-93f2-9d09271bd42a" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } } } }, "get": { "tags": [ "Certificate" ], "summary": "List all certificates on a gateway group", "operationId": "listCertificates", "description": "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.\n**Required IAM Permission:** Action `gateway:GetCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "exptime", "enum": [ "name", "exptime" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "sni_id", "in": "query", "required": false, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "sni_name", "description": "SNI name.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exptime", "in": "query", "required": false, "description": "Filter out results that expired before this time.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of certificates.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of certificates.", "items": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "common_name": { "type": "string", "description": "The common name of the certificate.", "example": "example.com" }, "subject_alt_names": { "type": "array", "description": "The subject alternative names of the certificate.", "items": { "type": "string", "example": "www.example.com" } }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string", "example": "1cf56bfe-7727-4584-93f2-9d09271bd42a" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/ca_certificates": { "post": { "tags": [ "CACertificate" ], "summary": "Create a CA certificate", "operationId": "createCACertificate", "description": "Create a CA certificate used to verify client certificates during mTLS handshakes in the gateway group.\n**Required IAM Permission:** Action `gateway:CreateCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The certificate description.", "type": "object", "required": [ "cert" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] } } } }, "responses": { "200": { "description": "CA certificate created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } } } }, "get": { "tags": [ "CACertificate" ], "summary": "List all CA certificates on a gateway group", "operationId": "listCACertificates", "description": "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.\n**Required IAM Permission:** Action `gateway:GetCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "exptime", "enum": [ "name", "exptime" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "sni_id", "in": "query", "required": false, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "sni_name", "description": "SNI name.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "exptime", "in": "query", "required": false, "description": "Filter out results that expired before this time.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of CA certificates.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of certificates.", "items": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/snis": { "post": { "tags": [ "SNI" ], "summary": "Create an SNI", "operationId": "createSNI", "description": "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.\n**Required IAM Permission:** Action `gateway:CreateSNI`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The sni description.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "domain": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "certificates": { "type": "array", "minItems": 1, "description": "An array of certificates.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "mtls": { "type": "object", "description": "mTLS configurations.", "properties": { "enabled": { "type": "boolean", "description": "If true, enable mTLS.", "default": false, "example": true }, "ca_certificates": { "type": "array", "minItems": 1, "description": "An array of CA certificates used for mTLS.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "ssl_protocols": { "type": "array", "description": "An array of TLS protocol versions.", "items": { "type": "string", "enum": [ "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] } } } ] } } } }, "responses": { "200": { "description": "SNI created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "domain": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "certificates": { "type": "array", "minItems": 1, "description": "An array of certificates.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "mtls": { "type": "object", "description": "mTLS configurations.", "properties": { "enabled": { "type": "boolean", "description": "If true, enable mTLS.", "default": false, "example": true }, "ca_certificates": { "type": "array", "minItems": 1, "description": "An array of CA certificates used for mTLS.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "ssl_protocols": { "type": "array", "description": "An array of TLS protocol versions.", "items": { "type": "string", "enum": [ "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } } } }, "get": { "tags": [ "SNI" ], "summary": "List all SNIs on a gateway group", "operationId": "listSNIs", "description": "List SNI configurations for the gateway group, including hostname and mTLS related settings. Use filters to locate entries by domain, labels, or mTLS enablement.\n**Required IAM Permission:** Action `gateway:GetSNI`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "name", "enum": [ "name" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "domain", "description": "The domain of the SNI.", "in": "query", "required": false, "schema": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, { "name": "mtls_enabled", "description": "If true, enable mTLS.", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "boolean" } } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of SNIs.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of SNIs.", "items": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "domain": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "certificates": { "type": "array", "minItems": 1, "description": "An array of certificates.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "mtls": { "type": "object", "description": "mTLS configurations.", "properties": { "enabled": { "type": "boolean", "description": "If true, enable mTLS.", "default": false, "example": true }, "ca_certificates": { "type": "array", "minItems": 1, "description": "An array of CA certificates used for mTLS.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "ssl_protocols": { "type": "array", "description": "An array of TLS protocol versions.", "items": { "type": "string", "enum": [ "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/certificates/{certificate_id}": { "get": { "tags": [ "Certificate" ], "summary": "Get a certificate on a gateway group", "operationId": "getCertificate", "description": "Retrieve details of a specific TLS server certificate in the gateway group, including its configured metadata and bindings.\n**Required IAM Permission:** Action `gateway:GetCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "certificate_id", "description": "The unique identifier of the Certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the certificate.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "common_name": { "type": "string", "description": "The common name of the certificate.", "example": "example.com" }, "subject_alt_names": { "type": "array", "description": "The subject alternative names of the certificate.", "items": { "type": "string", "example": "www.example.com" } }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string", "example": "1cf56bfe-7727-4584-93f2-9d09271bd42a" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Certificate" ], "summary": "Update a certificate on a gateway group", "operationId": "putCertificate", "description": "Replace the full configuration of an existing TLS server certificate in the gateway group. This operation may impact HTTPS traffic using this certificate.\n**Required IAM Permission:** Action `gateway:UpdateCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "certificate_id", "description": "The unique identifier of the Certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The certificate description.", "type": "object", "required": [ "key", "cert" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "key": { "type": "string", "description": "Private key.", "oneOf": [ { "title": "Private Key Reference", "description": "Path to the private key in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Private Key Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } ] } } } ] } } } }, "responses": { "200": { "description": "Certificate updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "common_name": { "type": "string", "description": "The common name of the certificate.", "example": "example.com" }, "subject_alt_names": { "type": "array", "description": "The subject alternative names of the certificate.", "items": { "type": "string", "example": "www.example.com" } }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string", "example": "1cf56bfe-7727-4584-93f2-9d09271bd42a" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Certificate" ], "summary": "Patch a certificate on a gateway group", "operationId": "patchCertificate", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdateCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "certificate_id", "description": "The unique identifier of the Certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Certificate updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "common_name": { "type": "string", "description": "The common name of the certificate.", "example": "example.com" }, "subject_alt_names": { "type": "array", "description": "The subject alternative names of the certificate.", "items": { "type": "string", "example": "www.example.com" } }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string", "example": "1cf56bfe-7727-4584-93f2-9d09271bd42a" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Certificate" ], "summary": "Delete a certificate on a gateway group", "operationId": "deleteCertificate", "description": "Delete a TLS server certificate from the gateway group. Ensure no active SNI or route still depends on this certificate before removal.\n**Required IAM Permission:** Action `gateway:DeleteCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "certificate_id", "description": "The unique identifier of the Certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/ca_certificates/{ca_certificate_id}": { "get": { "tags": [ "CACertificate" ], "summary": "Get a CA certificate on a gateway group", "operationId": "getCACertificate", "description": "Retrieve details of a specific CA certificate configured in the gateway group for mTLS validation.\n**Required IAM Permission:** Action `gateway:GetCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "ca_certificate_id", "description": "The unique identifier of the certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the CA certificate.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "CACertificate" ], "summary": "Update a CA certificate on a gateway group", "operationId": "putCACertificate", "description": "Replace the full configuration of an existing CA certificate used for client certificate verification. Changes can affect mTLS authentication for related traffic.\n**Required IAM Permission:** Action `gateway:UpdateCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "ca_certificate_id", "description": "The unique identifier of the certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The certificate description.", "type": "object", "required": [ "cert" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] } } } }, "responses": { "200": { "description": "CA certificate updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "CACertificate" ], "summary": "Patch a CA certificate on a gateway group", "operationId": "patchCACertificate", "description": "Partially update a CA certificate with JSON Patch (RFC 6902) operations. Use patching for targeted changes without sending the full CA certificate payload.\n**Required IAM Permission:** Action `gateway:UpdateCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "ca_certificate_id", "description": "The unique identifier of the certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "CA certificate updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "CACertificate" ], "summary": "Delete a CA certificate on a gateway group", "operationId": "deleteCACertificate", "description": "Delete a CA certificate from the gateway group. Confirm no active mTLS SNI or client verification flow still relies on this certificate.\n**Required IAM Permission:** Action `gateway:DeleteCertificate`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "ca_certificate_id", "description": "The unique identifier of the certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/snis/{sni_id}": { "get": { "tags": [ "SNI" ], "summary": "Get an SNI on a gateway group", "operationId": "getSNI", "description": "Retrieve the configuration of a specific SNI entry in the gateway group, including bound domains and certificate references.\n**Required IAM Permission:** Action `gateway:GetSNI`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "sni_id", "description": "The unique identifier of the SNI object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the SNI.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "domain": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "certificates": { "type": "array", "minItems": 1, "description": "An array of certificates.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "mtls": { "type": "object", "description": "mTLS configurations.", "properties": { "enabled": { "type": "boolean", "description": "If true, enable mTLS.", "default": false, "example": true }, "ca_certificates": { "type": "array", "minItems": 1, "description": "An array of CA certificates used for mTLS.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "ssl_protocols": { "type": "array", "description": "An array of TLS protocol versions.", "items": { "type": "string", "enum": [ "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "SNI" ], "summary": "Update an SNI on a gateway group", "operationId": "putSNI", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdateSNI`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "sni_id", "description": "The unique identifier of the SNI object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The sni description.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "domain": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "certificates": { "type": "array", "minItems": 1, "description": "An array of certificates.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "mtls": { "type": "object", "description": "mTLS configurations.", "properties": { "enabled": { "type": "boolean", "description": "If true, enable mTLS.", "default": false, "example": true }, "ca_certificates": { "type": "array", "minItems": 1, "description": "An array of CA certificates used for mTLS.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "ssl_protocols": { "type": "array", "description": "An array of TLS protocol versions.", "items": { "type": "string", "enum": [ "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] } } } ] } } } }, "responses": { "200": { "description": "SNI updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "domain": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "certificates": { "type": "array", "minItems": 1, "description": "An array of certificates.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "mtls": { "type": "object", "description": "mTLS configurations.", "properties": { "enabled": { "type": "boolean", "description": "If true, enable mTLS.", "default": false, "example": true }, "ca_certificates": { "type": "array", "minItems": 1, "description": "An array of CA certificates used for mTLS.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "ssl_protocols": { "type": "array", "description": "An array of TLS protocol versions.", "items": { "type": "string", "enum": [ "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "SNI" ], "summary": "Patch an SNI on a gateway group", "operationId": "patchSNI", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdateSNI`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "sni_id", "description": "The unique identifier of the SNI object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "SNI updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "domain": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "certificates": { "type": "array", "minItems": 1, "description": "An array of certificates.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "mtls": { "type": "object", "description": "mTLS configurations.", "properties": { "enabled": { "type": "boolean", "description": "If true, enable mTLS.", "default": false, "example": true }, "ca_certificates": { "type": "array", "minItems": 1, "description": "An array of CA certificates used for mTLS.", "items": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } }, "skip_mtls_uri_regex": { "type": "array", "description": "URI regular expressions to skip mTLS verification. Requests matching any of these patterns will bypass client certificate verification.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } } } }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "ssl_protocols": { "type": "array", "description": "An array of TLS protocol versions.", "items": { "type": "string", "enum": [ "TLSv1.1", "TLSv1.2", "TLSv1.3" ] }, "default": [ "TLSv1.2", "TLSv1.3" ] } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "SNI" ], "summary": "Delete an SNI on a gateway group", "operationId": "deleteSNI", "description": "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.\n**Required IAM Permission:** Action `gateway:DeleteSNI`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "sni_id", "description": "The unique identifier of the SNI object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/consumers": { "post": { "tags": [ "Consumer" ], "summary": "Create a consumer on a gateway group", "operationId": "createConsumer", "description": "IAM Action: `gateway:CreateConsumer`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/*`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The consumer description.", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Consumer created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The consumer with management fields.", "allOf": [ { "description": "The consumer description.", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Consumer" ], "summary": "List all consumers on a gateway group", "operationId": "listConsumers", "description": "IAM Action: `gateway:GetConsumer`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order consumers by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "username" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of consumers.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of consumers.", "items": { "description": "The consumer with management fields.", "allOf": [ { "description": "The consumer description.", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/consumers/{username}": { "get": { "tags": [ "Consumer" ], "summary": "Get a consumer on a gateway group", "operationId": "getConsumer", "description": "IAM Action: `gateway:GetConsumer`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the consumer.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The consumer with management fields.", "allOf": [ { "description": "The consumer description.", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Consumer" ], "summary": "Update a consumer on a gateway group", "operationId": "upsertConsumer", "description": "IAM Action: `gateway:UpdateConsumer`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The consumer description.", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Consumer updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The consumer with management fields.", "allOf": [ { "description": "The consumer description.", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Consumer" ], "summary": "Delete a consumer", "operationId": "deleteConsumer", "description": "IAM Action: `gateway:DeleteConsumer`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Consumer" ], "summary": "Update a consumer on a gateway group", "operationId": "updateConsumer", "description": "IAM Action: `gateway:UpdateConsumer`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Consumer updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The consumer with management fields.", "allOf": [ { "description": "The consumer description.", "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/consumers/{username}/credentials": { "post": { "tags": [ "Consumer" ], "summary": "Create a consumer credential on a gateway group", "operationId": "createConsumerCredential", "description": "IAM Action: `gateway:CreateConsumerCredential`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The consumer credential description.", "type": "object", "required": [ "name", "plugins" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "plugins": { "type": "object", "maxProperties": 1, "minProperties": 1, "description": "Plugin configuration.", "oneOf": [ { "title": "key-auth", "required": [ "key-auth" ], "properties": { "key-auth": { "type": "object", "description": "`key-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`key-auth` user key.", "example": "john-key" } } } } }, { "title": "basic-auth", "required": [ "basic-auth" ], "properties": { "basic-auth": { "type": "object", "description": "`basic-auth` plugin configurations.", "properties": { "username": { "type": "string", "description": "`basic-auth` unique username.", "example": "john" }, "password": { "type": "string", "description": "`basic-auth` user password.", "example": "john-secret" } } } } }, { "title": "hmac-auth", "required": [ "hmac-auth" ], "properties": { "hmac-auth": { "type": "object", "description": "`hmac-auth` plugin configurations.", "properties": { "key_id": { "type": "string", "description": "`hmac-auth` key unique identifier.", "example": "john-key" }, "secret_key": { "type": "string", "description": "`hmac-auth` secret key.", "example": "john-secret-key" } } } } }, { "title": "jwt-auth", "required": [ "jwt-auth" ], "properties": { "jwt-auth": { "type": "object", "description": "`jwt-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`jwt-auth` key unique identifier.", "example": "john-key" }, "secret": { "type": "string", "description": "`jwt-auth` secret.", "example": "jack-hs256-secret" } } } } } ] }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Consumer credential created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The consumer credential with management fields.", "allOf": [ { "description": "The consumer credential description.", "type": "object", "required": [ "name", "plugins" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "plugins": { "type": "object", "maxProperties": 1, "minProperties": 1, "description": "Plugin configuration.", "oneOf": [ { "title": "key-auth", "required": [ "key-auth" ], "properties": { "key-auth": { "type": "object", "description": "`key-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`key-auth` user key.", "example": "john-key" } } } } }, { "title": "basic-auth", "required": [ "basic-auth" ], "properties": { "basic-auth": { "type": "object", "description": "`basic-auth` plugin configurations.", "properties": { "username": { "type": "string", "description": "`basic-auth` unique username.", "example": "john" }, "password": { "type": "string", "description": "`basic-auth` user password.", "example": "john-secret" } } } } }, { "title": "hmac-auth", "required": [ "hmac-auth" ], "properties": { "hmac-auth": { "type": "object", "description": "`hmac-auth` plugin configurations.", "properties": { "key_id": { "type": "string", "description": "`hmac-auth` key unique identifier.", "example": "john-key" }, "secret_key": { "type": "string", "description": "`hmac-auth` secret key.", "example": "john-secret-key" } } } } }, { "title": "jwt-auth", "required": [ "jwt-auth" ], "properties": { "jwt-auth": { "type": "object", "description": "`jwt-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`jwt-auth` key unique identifier.", "example": "john-key" }, "secret": { "type": "string", "description": "`jwt-auth` secret.", "example": "jack-hs256-secret" } } } } } ] }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Consumer" ], "summary": "List all consumer credentials on a gateway group", "operationId": "listConsumerCredentials", "description": "IAM Action: `gateway:GetConsumerCredential`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "plugin_name", "description": "the plugin name of the consumer credential.", "in": "query", "required": false, "schema": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order consumers by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "name" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of consumer credentials.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of consumer credentials.", "items": { "description": "The consumer credential with management fields.", "allOf": [ { "description": "The consumer credential description.", "type": "object", "required": [ "name", "plugins" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "plugins": { "type": "object", "maxProperties": 1, "minProperties": 1, "description": "Plugin configuration.", "oneOf": [ { "title": "key-auth", "required": [ "key-auth" ], "properties": { "key-auth": { "type": "object", "description": "`key-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`key-auth` user key.", "example": "john-key" } } } } }, { "title": "basic-auth", "required": [ "basic-auth" ], "properties": { "basic-auth": { "type": "object", "description": "`basic-auth` plugin configurations.", "properties": { "username": { "type": "string", "description": "`basic-auth` unique username.", "example": "john" }, "password": { "type": "string", "description": "`basic-auth` user password.", "example": "john-secret" } } } } }, { "title": "hmac-auth", "required": [ "hmac-auth" ], "properties": { "hmac-auth": { "type": "object", "description": "`hmac-auth` plugin configurations.", "properties": { "key_id": { "type": "string", "description": "`hmac-auth` key unique identifier.", "example": "john-key" }, "secret_key": { "type": "string", "description": "`hmac-auth` secret key.", "example": "john-secret-key" } } } } }, { "title": "jwt-auth", "required": [ "jwt-auth" ], "properties": { "jwt-auth": { "type": "object", "description": "`jwt-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`jwt-auth` key unique identifier.", "example": "john-key" }, "secret": { "type": "string", "description": "`jwt-auth` secret.", "example": "jack-hs256-secret" } } } } } ] }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/consumers/{username}/credentials/{credential_id}": { "get": { "tags": [ "Consumer" ], "summary": "Get a consumer credential on a gateway group", "operationId": "getConsumerCredential", "description": "IAM Action: `gateway:GetConsumerCredential`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "credential_id", "description": "The unique identifier of the consumer credential.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the consumer credential.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The consumer credential with management fields.", "allOf": [ { "description": "The consumer credential description.", "type": "object", "required": [ "name", "plugins" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "plugins": { "type": "object", "maxProperties": 1, "minProperties": 1, "description": "Plugin configuration.", "oneOf": [ { "title": "key-auth", "required": [ "key-auth" ], "properties": { "key-auth": { "type": "object", "description": "`key-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`key-auth` user key.", "example": "john-key" } } } } }, { "title": "basic-auth", "required": [ "basic-auth" ], "properties": { "basic-auth": { "type": "object", "description": "`basic-auth` plugin configurations.", "properties": { "username": { "type": "string", "description": "`basic-auth` unique username.", "example": "john" }, "password": { "type": "string", "description": "`basic-auth` user password.", "example": "john-secret" } } } } }, { "title": "hmac-auth", "required": [ "hmac-auth" ], "properties": { "hmac-auth": { "type": "object", "description": "`hmac-auth` plugin configurations.", "properties": { "key_id": { "type": "string", "description": "`hmac-auth` key unique identifier.", "example": "john-key" }, "secret_key": { "type": "string", "description": "`hmac-auth` secret key.", "example": "john-secret-key" } } } } }, { "title": "jwt-auth", "required": [ "jwt-auth" ], "properties": { "jwt-auth": { "type": "object", "description": "`jwt-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`jwt-auth` key unique identifier.", "example": "john-key" }, "secret": { "type": "string", "description": "`jwt-auth` secret.", "example": "jack-hs256-secret" } } } } } ] }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Consumer" ], "summary": "Update a consumer credential on a gateway group", "operationId": "upsertConsumerCredential", "description": "IAM Action: `gateway:UpdateConsumerCredential`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "credential_id", "description": "The unique identifier of the consumer credential.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The consumer credential description.", "type": "object", "required": [ "name", "plugins" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "plugins": { "type": "object", "maxProperties": 1, "minProperties": 1, "description": "Plugin configuration.", "oneOf": [ { "title": "key-auth", "required": [ "key-auth" ], "properties": { "key-auth": { "type": "object", "description": "`key-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`key-auth` user key.", "example": "john-key" } } } } }, { "title": "basic-auth", "required": [ "basic-auth" ], "properties": { "basic-auth": { "type": "object", "description": "`basic-auth` plugin configurations.", "properties": { "username": { "type": "string", "description": "`basic-auth` unique username.", "example": "john" }, "password": { "type": "string", "description": "`basic-auth` user password.", "example": "john-secret" } } } } }, { "title": "hmac-auth", "required": [ "hmac-auth" ], "properties": { "hmac-auth": { "type": "object", "description": "`hmac-auth` plugin configurations.", "properties": { "key_id": { "type": "string", "description": "`hmac-auth` key unique identifier.", "example": "john-key" }, "secret_key": { "type": "string", "description": "`hmac-auth` secret key.", "example": "john-secret-key" } } } } }, { "title": "jwt-auth", "required": [ "jwt-auth" ], "properties": { "jwt-auth": { "type": "object", "description": "`jwt-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`jwt-auth` key unique identifier.", "example": "john-key" }, "secret": { "type": "string", "description": "`jwt-auth` secret.", "example": "jack-hs256-secret" } } } } } ] }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Consumer credential updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The consumer credential with management fields.", "allOf": [ { "description": "The consumer credential description.", "type": "object", "required": [ "name", "plugins" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "plugins": { "type": "object", "maxProperties": 1, "minProperties": 1, "description": "Plugin configuration.", "oneOf": [ { "title": "key-auth", "required": [ "key-auth" ], "properties": { "key-auth": { "type": "object", "description": "`key-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`key-auth` user key.", "example": "john-key" } } } } }, { "title": "basic-auth", "required": [ "basic-auth" ], "properties": { "basic-auth": { "type": "object", "description": "`basic-auth` plugin configurations.", "properties": { "username": { "type": "string", "description": "`basic-auth` unique username.", "example": "john" }, "password": { "type": "string", "description": "`basic-auth` user password.", "example": "john-secret" } } } } }, { "title": "hmac-auth", "required": [ "hmac-auth" ], "properties": { "hmac-auth": { "type": "object", "description": "`hmac-auth` plugin configurations.", "properties": { "key_id": { "type": "string", "description": "`hmac-auth` key unique identifier.", "example": "john-key" }, "secret_key": { "type": "string", "description": "`hmac-auth` secret key.", "example": "john-secret-key" } } } } }, { "title": "jwt-auth", "required": [ "jwt-auth" ], "properties": { "jwt-auth": { "type": "object", "description": "`jwt-auth` plugin configurations.", "properties": { "key": { "type": "string", "description": "`jwt-auth` key unique identifier.", "example": "john-key" }, "secret": { "type": "string", "description": "`jwt-auth` secret.", "example": "jack-hs256-secret" } } } } } ] }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Consumer" ], "summary": "Delete a consumer credential", "operationId": "deleteConsumerCredential", "description": "IAM Action: `gateway:DeleteConsumerCredential`, Resource: `arn:api7:gateway:gatewaygroup/%s/consumer/%s`", "parameters": [ { "name": "username", "description": "The unique identifier of the consumer.", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-]+$", "description": "The unique identifier of the consumer.", "example": "johndoe" } }, { "name": "credential_id", "description": "The unique identifier of the consumer credential.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "401": { "description": "Unauthorized — Authentication is required. Provide a valid API key via the X-API-KEY header or use Basic Auth credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/dcr_providers": { "post": { "tags": [ "Provider Portal - DCR Provider" ], "summary": "Create an DCR provider", "operationId": "createDCRProvider", "description": "IAM Action: `portal:CreateDCRProvider`, Resource: `arn:api7:portal:dcrprovider/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "issuer" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the Dynamic Client Registration (DCR) Provider." }, "provider_type": { "type": "string", "enum": [ "oidc", "http_bridge" ], "default": "oidc", "description": "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": { "type": "string", "format": "uri", "description": "The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation." }, "provider_config": { "type": "object", "description": "Provider-specific configuration. Required when provider_type is \"http_bridge\".", "properties": { "base_url": { "type": "string", "format": "uri", "description": "The base URL of the HTTP Bridge service." } } }, "headers": { "type": "object", "description": "Custom headers to include in requests to the Authorization Server or HTTP Bridge.", "example": { "Authorization": "Bearer $TOKEN" }, "additionalProperties": { "type": "string" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the DCR provider.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "required": [ "name", "issuer" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the Dynamic Client Registration (DCR) Provider." }, "provider_type": { "type": "string", "enum": [ "oidc", "http_bridge" ], "default": "oidc", "description": "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": { "type": "string", "format": "uri", "description": "The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation." }, "provider_config": { "type": "object", "description": "Provider-specific configuration. Required when provider_type is \"http_bridge\".", "properties": { "base_url": { "type": "string", "format": "uri", "description": "The base URL of the HTTP Bridge service." } } }, "headers": { "type": "object", "description": "Custom headers to include in requests to the Authorization Server or HTTP Bridge.", "example": { "Authorization": "Bearer $TOKEN" }, "additionalProperties": { "type": "string" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Provider Portal - DCR Provider" ], "summary": "List all DCR providers", "operationId": "listDCRProviders", "description": "IAM Action: `portal:GetDCRProvider`, Resource: `arn:api7:portal:dcrprovider/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of DCR providers.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of DCRProvider.", "items": { "allOf": [ { "type": "object", "required": [ "name", "issuer" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the Dynamic Client Registration (DCR) Provider." }, "provider_type": { "type": "string", "enum": [ "oidc", "http_bridge" ], "default": "oidc", "description": "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": { "type": "string", "format": "uri", "description": "The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation." }, "provider_config": { "type": "object", "description": "Provider-specific configuration. Required when provider_type is \"http_bridge\".", "properties": { "base_url": { "type": "string", "format": "uri", "description": "The base URL of the HTTP Bridge service." } } }, "headers": { "type": "object", "description": "Custom headers to include in requests to the Authorization Server or HTTP Bridge.", "example": { "Authorization": "Bearer $TOKEN" }, "additionalProperties": { "type": "string" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/dcr_providers/{dcr_provider_id}": { "get": { "tags": [ "Provider Portal - DCR Provider" ], "summary": "Get an DCR provider", "operationId": "getDCRProvider", "description": "IAM Action: `portal:GetDCRProvider`, Resource: `arn:api7:portal:dcrprovider/%s`", "parameters": [ { "name": "dcr_provider_id", "description": "The unique identifier of the DCR Provider.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved or modified the DCR provider.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "required": [ "name", "issuer" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the Dynamic Client Registration (DCR) Provider." }, "provider_type": { "type": "string", "enum": [ "oidc", "http_bridge" ], "default": "oidc", "description": "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": { "type": "string", "format": "uri", "description": "The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation." }, "provider_config": { "type": "object", "description": "Provider-specific configuration. Required when provider_type is \"http_bridge\".", "properties": { "base_url": { "type": "string", "format": "uri", "description": "The base URL of the HTTP Bridge service." } } }, "headers": { "type": "object", "description": "Custom headers to include in requests to the Authorization Server or HTTP Bridge.", "example": { "Authorization": "Bearer $TOKEN" }, "additionalProperties": { "type": "string" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Provider Portal - DCR Provider" ], "summary": "Update an DCR Provider", "operationId": "updateDCRProvider", "description": "IAM Action: `portal:UpdateDCRProvider`, Resource: `arn:api7:portal:dcrprovider/%s`", "parameters": [ { "name": "dcr_provider_id", "description": "The unique identifier of the DCR Provider.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "issuer" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the Dynamic Client Registration (DCR) Provider." }, "provider_type": { "type": "string", "enum": [ "oidc", "http_bridge" ], "default": "oidc", "description": "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": { "type": "string", "format": "uri", "description": "The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation." }, "provider_config": { "type": "object", "description": "Provider-specific configuration. Required when provider_type is \"http_bridge\".", "properties": { "base_url": { "type": "string", "format": "uri", "description": "The base URL of the HTTP Bridge service." } } }, "headers": { "type": "object", "description": "Custom headers to include in requests to the Authorization Server or HTTP Bridge.", "example": { "Authorization": "Bearer $TOKEN" }, "additionalProperties": { "type": "string" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the DCR provider.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "required": [ "name", "issuer" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the Dynamic Client Registration (DCR) Provider." }, "provider_type": { "type": "string", "enum": [ "oidc", "http_bridge" ], "default": "oidc", "description": "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": { "type": "string", "format": "uri", "description": "The issuer URL of the Authorization Server. Required for all provider types — used by the data plane (APISIX) for token validation." }, "provider_config": { "type": "object", "description": "Provider-specific configuration. Required when provider_type is \"http_bridge\".", "properties": { "base_url": { "type": "string", "format": "uri", "description": "The base URL of the HTTP Bridge service." } } }, "headers": { "type": "object", "description": "Custom headers to include in requests to the Authorization Server or HTTP Bridge.", "example": { "Authorization": "Bearer $TOKEN" }, "additionalProperties": { "type": "string" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Provider Portal - DCR Provider" ], "summary": "Delete an DCR Provider", "operationId": "deleteDCRProvider", "description": "IAM Action: `portal:DeleteDCRProvider`, Resource: `arn:api7:portal:dcrprovider/%s`", "parameters": [ { "name": "dcr_provider_id", "description": "The unique identifier of the DCR Provider.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/api_products": { "post": { "tags": [ "Provider Portal - API Product" ], "summary": "Create an API product in Provider Portal", "operationId": "createAPIProduct-ProviderPortal", "description": "IAM Action: `portal:CreateAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/*`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The API product description.", "type": "object", "oneOf": [ { "title": "Gateway API Product", "type": "object", "required": [ "type", "name", "linked_gateway_services" ], "properties": { "type": { "type": "string", "enum": [ "gateway" ], "default": "gateway" }, "name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "logo": { "type": "string", "description": "The base64-encoded logo image of the API product." }, "desc": { "type": "string", "description": "The description of the API product.", "example": "The Weather Insights API provides real-time and historical weather data for any location worldwide." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "auth": { "type": "object", "description": "The authentication configuration of the API product.", "additionalProperties": false, "minProperties": 1, "example": { "key-auth": { "header": "apikey", "hide_credentials": false, "query": "apikey" } }, "properties": { "key-auth": { "type": "object", "additionalProperties": false, "description": "Key authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." }, "query": { "type": "string", "default": "apikey", "description": "The query string to get the key from. Lower priority than header." }, "header": { "type": "string", "default": "apikey", "description": "The header to get the key from." } } }, "basic-auth": { "type": "object", "additionalProperties": false, "description": "Basic authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." } } }, "dcr": { "type": "object", "additionalProperties": false, "description": "DCR authentication configurations.", "required": [ "dcr_provider_id" ], "properties": { "dcr_provider_id": { "description": "ID of the DCR provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } }, "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "minItems": 1, "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "service_id": { "description": "The service template ID of the published service.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "linked_hosts": { "type": "array", "description": "Select one or more hosts configured for the gateway service to be published to the API portal. If not set, it means using all hosts of the gateway service.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "subscription_auto_approval": { "type": "boolean", "default": false, "description": "If true, the subscription is automatically approved." }, "can_view_unsubscribed": { "type": "boolean", "description": "If true, developers can view the unsubscribed API.", "default": true }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "title": "External API Product", "allOf": [ { "type": "object", "required": [ "name", "type", "raw_openapi" ], "properties": { "type": { "type": "string", "description": "Type of API product.", "enum": [ "external" ], "default": "external" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "raw_openapi": { "type": "string", "minLength": 1, "description": "The content of the OpenAPI YAML file.", "example": "Raw OpenAPI spec" }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "anyOf": [ { "type": "object", "required": [ "server_url" ], "properties": { "server_url": { "deprecated": true, "type": "string", "minLength": 1, "maxLength": 4096, "description": "The server URL. It should be configured if the server URL is not defined in the OpenAPI spec.", "example": "http://localhost:8080" } } }, { "type": "object", "required": [ "server_urls" ], "properties": { "server_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The server URLs. It should be configured if the server URLs are not defined in the OpenAPI spec.", "example": [ "http://localhost:8080", "http://localhost:8081" ] } } } ] } ] } ] } } } }, "responses": { "200": { "description": "API product created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The API product fields.", "oneOf": [ { "title": "Gateway API Product", "type": "object", "allOf": [ { "type": "object", "required": [ "type", "name", "linked_gateway_services" ], "properties": { "type": { "type": "string", "enum": [ "gateway" ], "default": "gateway" }, "name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "logo": { "type": "string", "description": "The base64-encoded logo image of the API product." }, "desc": { "type": "string", "description": "The description of the API product.", "example": "The Weather Insights API provides real-time and historical weather data for any location worldwide." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "auth": { "type": "object", "description": "The authentication configuration of the API product.", "additionalProperties": false, "minProperties": 1, "example": { "key-auth": { "header": "apikey", "hide_credentials": false, "query": "apikey" } }, "properties": { "key-auth": { "type": "object", "additionalProperties": false, "description": "Key authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." }, "query": { "type": "string", "default": "apikey", "description": "The query string to get the key from. Lower priority than header." }, "header": { "type": "string", "default": "apikey", "description": "The header to get the key from." } } }, "basic-auth": { "type": "object", "additionalProperties": false, "description": "Basic authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." } } }, "dcr": { "type": "object", "additionalProperties": false, "description": "DCR authentication configurations.", "required": [ "dcr_provider_id" ], "properties": { "dcr_provider_id": { "description": "ID of the DCR provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } }, "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "minItems": 1, "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "service_id": { "description": "The service template ID of the published service.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "linked_hosts": { "type": "array", "description": "Select one or more hosts configured for the gateway service to be published to the API portal. If not set, it means using all hosts of the gateway service.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "subscription_auto_approval": { "type": "boolean", "default": false, "description": "If true, the subscription is automatically approved." }, "can_view_unsubscribed": { "type": "boolean", "description": "If true, developers can view the unsubscribed API.", "default": true }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "type": "object", "properties": { "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "items": { "type": "object", "description": "The gateway group and service that the API product is linked to.", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "name": { "description": "The service name.", "example": "Weather Insights API", "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "string", "description": "The version of the published service.", "example": "1.3.2" }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "hosts": { "type": "array", "items": { "example": "weatherinsights.com", "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$" } }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "openapi_title": { "type": "string", "description": "The title of the OpenAPI file.", "example": "Weather Insights API - OpenAPI 3.0" } } } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "title": "External API Product", "type": "object", "allOf": [ { "allOf": [ { "type": "object", "required": [ "name", "type", "raw_openapi" ], "properties": { "type": { "type": "string", "description": "Type of API product.", "enum": [ "external" ], "default": "external" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "raw_openapi": { "type": "string", "minLength": 1, "description": "The content of the OpenAPI YAML file.", "example": "Raw OpenAPI spec" }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "anyOf": [ { "type": "object", "required": [ "server_url" ], "properties": { "server_url": { "deprecated": true, "type": "string", "minLength": 1, "maxLength": 4096, "description": "The server URL. It should be configured if the server URL is not defined in the OpenAPI spec.", "example": "http://localhost:8080" } } }, { "type": "object", "required": [ "server_urls" ], "properties": { "server_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The server URLs. It should be configured if the server URLs are not defined in the OpenAPI spec.", "example": [ "http://localhost:8080", "http://localhost:8081" ] } } } ] } ] }, { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "desc": { "type": "string", "description": "Description." }, "api_desc": { "type": "string", "description": "API description." }, "api_count": { "type": "number", "format": "int32", "description": "API count.", "example": 10 } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } ] }, { "type": "object", "properties": { "notifications": { "description": "Notification details.", "type": "array", "items": { "oneOf": [ { "title": "Email", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "email" ] }, "email_subject": { "type": "string", "description": "Email subject.", "example": "API7 Enterprise alert." }, "content": { "type": "string", "description": "Email content.", "example": "This is a alert testing email." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] }, { "title": "Webhook", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "webhook" ] }, "message": { "type": "string", "description": "Notification message.", "example": "This is a alert testing message." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] } ] } } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Provider Portal - API Product" ], "summary": "List all API products in Provider Portal", "operationId": "listAPIProducts-ProviderPortal", "description": "IAM Action: `portal:GetAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "service_id", "description": "The unique identifier of the service template.", "in": "query", "required": false, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of API products.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of APIProduct.", "items": { "description": "The API product fields.", "oneOf": [ { "title": "Gateway API Product", "type": "object", "allOf": [ { "type": "object", "required": [ "type", "name", "linked_gateway_services" ], "properties": { "type": { "type": "string", "enum": [ "gateway" ], "default": "gateway" }, "name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "logo": { "type": "string", "description": "The base64-encoded logo image of the API product." }, "desc": { "type": "string", "description": "The description of the API product.", "example": "The Weather Insights API provides real-time and historical weather data for any location worldwide." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "auth": { "type": "object", "description": "The authentication configuration of the API product.", "additionalProperties": false, "minProperties": 1, "example": { "key-auth": { "header": "apikey", "hide_credentials": false, "query": "apikey" } }, "properties": { "key-auth": { "type": "object", "additionalProperties": false, "description": "Key authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." }, "query": { "type": "string", "default": "apikey", "description": "The query string to get the key from. Lower priority than header." }, "header": { "type": "string", "default": "apikey", "description": "The header to get the key from." } } }, "basic-auth": { "type": "object", "additionalProperties": false, "description": "Basic authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." } } }, "dcr": { "type": "object", "additionalProperties": false, "description": "DCR authentication configurations.", "required": [ "dcr_provider_id" ], "properties": { "dcr_provider_id": { "description": "ID of the DCR provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } }, "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "minItems": 1, "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "service_id": { "description": "The service template ID of the published service.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "linked_hosts": { "type": "array", "description": "Select one or more hosts configured for the gateway service to be published to the API portal. If not set, it means using all hosts of the gateway service.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "subscription_auto_approval": { "type": "boolean", "default": false, "description": "If true, the subscription is automatically approved." }, "can_view_unsubscribed": { "type": "boolean", "description": "If true, developers can view the unsubscribed API.", "default": true }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "type": "object", "properties": { "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "items": { "type": "object", "description": "The gateway group and service that the API product is linked to.", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "name": { "description": "The service name.", "example": "Weather Insights API", "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "string", "description": "The version of the published service.", "example": "1.3.2" }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "hosts": { "type": "array", "items": { "example": "weatherinsights.com", "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$" } }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "openapi_title": { "type": "string", "description": "The title of the OpenAPI file.", "example": "Weather Insights API - OpenAPI 3.0" } } } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "title": "External API Product", "type": "object", "allOf": [ { "allOf": [ { "type": "object", "required": [ "name", "type", "raw_openapi" ], "properties": { "type": { "type": "string", "description": "Type of API product.", "enum": [ "external" ], "default": "external" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "raw_openapi": { "type": "string", "minLength": 1, "description": "The content of the OpenAPI YAML file.", "example": "Raw OpenAPI spec" }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "anyOf": [ { "type": "object", "required": [ "server_url" ], "properties": { "server_url": { "deprecated": true, "type": "string", "minLength": 1, "maxLength": 4096, "description": "The server URL. It should be configured if the server URL is not defined in the OpenAPI spec.", "example": "http://localhost:8080" } } }, { "type": "object", "required": [ "server_urls" ], "properties": { "server_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The server URLs. It should be configured if the server URLs are not defined in the OpenAPI spec.", "example": [ "http://localhost:8080", "http://localhost:8081" ] } } } ] } ] }, { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "desc": { "type": "string", "description": "Description." }, "api_desc": { "type": "string", "description": "API description." }, "api_count": { "type": "number", "format": "int32", "description": "API count.", "example": 10 } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/api_products/{api_product_id}": { "get": { "tags": [ "Provider Portal - API Product" ], "summary": "Get an API product in Provider Portal", "operationId": "getAPIProduct-ProviderPortal", "description": "IAM Action: `portal:GetAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "api_product_id", "description": "The unique identifier of the API product.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the API product.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The API product fields.", "oneOf": [ { "title": "Gateway API Product", "type": "object", "allOf": [ { "type": "object", "required": [ "type", "name", "linked_gateway_services" ], "properties": { "type": { "type": "string", "enum": [ "gateway" ], "default": "gateway" }, "name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "logo": { "type": "string", "description": "The base64-encoded logo image of the API product." }, "desc": { "type": "string", "description": "The description of the API product.", "example": "The Weather Insights API provides real-time and historical weather data for any location worldwide." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "auth": { "type": "object", "description": "The authentication configuration of the API product.", "additionalProperties": false, "minProperties": 1, "example": { "key-auth": { "header": "apikey", "hide_credentials": false, "query": "apikey" } }, "properties": { "key-auth": { "type": "object", "additionalProperties": false, "description": "Key authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." }, "query": { "type": "string", "default": "apikey", "description": "The query string to get the key from. Lower priority than header." }, "header": { "type": "string", "default": "apikey", "description": "The header to get the key from." } } }, "basic-auth": { "type": "object", "additionalProperties": false, "description": "Basic authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." } } }, "dcr": { "type": "object", "additionalProperties": false, "description": "DCR authentication configurations.", "required": [ "dcr_provider_id" ], "properties": { "dcr_provider_id": { "description": "ID of the DCR provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } }, "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "minItems": 1, "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "service_id": { "description": "The service template ID of the published service.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "linked_hosts": { "type": "array", "description": "Select one or more hosts configured for the gateway service to be published to the API portal. If not set, it means using all hosts of the gateway service.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "subscription_auto_approval": { "type": "boolean", "default": false, "description": "If true, the subscription is automatically approved." }, "can_view_unsubscribed": { "type": "boolean", "description": "If true, developers can view the unsubscribed API.", "default": true }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "type": "object", "properties": { "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "items": { "type": "object", "description": "The gateway group and service that the API product is linked to.", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "name": { "description": "The service name.", "example": "Weather Insights API", "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "string", "description": "The version of the published service.", "example": "1.3.2" }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "hosts": { "type": "array", "items": { "example": "weatherinsights.com", "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$" } }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "openapi_title": { "type": "string", "description": "The title of the OpenAPI file.", "example": "Weather Insights API - OpenAPI 3.0" } } } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "title": "External API Product", "type": "object", "allOf": [ { "allOf": [ { "type": "object", "required": [ "name", "type", "raw_openapi" ], "properties": { "type": { "type": "string", "description": "Type of API product.", "enum": [ "external" ], "default": "external" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "raw_openapi": { "type": "string", "minLength": 1, "description": "The content of the OpenAPI YAML file.", "example": "Raw OpenAPI spec" }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "anyOf": [ { "type": "object", "required": [ "server_url" ], "properties": { "server_url": { "deprecated": true, "type": "string", "minLength": 1, "maxLength": 4096, "description": "The server URL. It should be configured if the server URL is not defined in the OpenAPI spec.", "example": "http://localhost:8080" } } }, { "type": "object", "required": [ "server_urls" ], "properties": { "server_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The server URLs. It should be configured if the server URLs are not defined in the OpenAPI spec.", "example": [ "http://localhost:8080", "http://localhost:8081" ] } } } ] } ] }, { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "desc": { "type": "string", "description": "Description." }, "api_desc": { "type": "string", "description": "API description." }, "api_count": { "type": "number", "format": "int32", "description": "API count.", "example": 10 } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } ] }, { "type": "object", "properties": { "notifications": { "description": "Notification details.", "type": "array", "items": { "oneOf": [ { "title": "Email", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "email" ] }, "email_subject": { "type": "string", "description": "Email subject.", "example": "API7 Enterprise alert." }, "content": { "type": "string", "description": "Email content.", "example": "This is a alert testing email." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] }, { "title": "Webhook", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "webhook" ] }, "message": { "type": "string", "description": "Notification message.", "example": "This is a alert testing message." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] } ] } } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Provider Portal - API Product" ], "summary": "Update an API product in Provider Portal", "operationId": "updateAPIProduct-ProviderPortal", "description": "IAM Action: `portal:UpdateAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "api_product_id", "description": "The unique identifier of the API product.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The API product description.", "type": "object", "oneOf": [ { "title": "Gateway API Product", "type": "object", "required": [ "type", "name", "linked_gateway_services" ], "properties": { "type": { "type": "string", "enum": [ "gateway" ], "default": "gateway" }, "name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "logo": { "type": "string", "description": "The base64-encoded logo image of the API product." }, "desc": { "type": "string", "description": "The description of the API product.", "example": "The Weather Insights API provides real-time and historical weather data for any location worldwide." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "auth": { "type": "object", "description": "The authentication configuration of the API product.", "additionalProperties": false, "minProperties": 1, "example": { "key-auth": { "header": "apikey", "hide_credentials": false, "query": "apikey" } }, "properties": { "key-auth": { "type": "object", "additionalProperties": false, "description": "Key authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." }, "query": { "type": "string", "default": "apikey", "description": "The query string to get the key from. Lower priority than header." }, "header": { "type": "string", "default": "apikey", "description": "The header to get the key from." } } }, "basic-auth": { "type": "object", "additionalProperties": false, "description": "Basic authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." } } }, "dcr": { "type": "object", "additionalProperties": false, "description": "DCR authentication configurations.", "required": [ "dcr_provider_id" ], "properties": { "dcr_provider_id": { "description": "ID of the DCR provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } }, "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "minItems": 1, "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "service_id": { "description": "The service template ID of the published service.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "linked_hosts": { "type": "array", "description": "Select one or more hosts configured for the gateway service to be published to the API portal. If not set, it means using all hosts of the gateway service.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "subscription_auto_approval": { "type": "boolean", "default": false, "description": "If true, the subscription is automatically approved." }, "can_view_unsubscribed": { "type": "boolean", "description": "If true, developers can view the unsubscribed API.", "default": true }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "title": "External API Product", "allOf": [ { "type": "object", "required": [ "name", "type", "raw_openapi" ], "properties": { "type": { "type": "string", "description": "Type of API product.", "enum": [ "external" ], "default": "external" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "raw_openapi": { "type": "string", "minLength": 1, "description": "The content of the OpenAPI YAML file.", "example": "Raw OpenAPI spec" }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "anyOf": [ { "type": "object", "required": [ "server_url" ], "properties": { "server_url": { "deprecated": true, "type": "string", "minLength": 1, "maxLength": 4096, "description": "The server URL. It should be configured if the server URL is not defined in the OpenAPI spec.", "example": "http://localhost:8080" } } }, { "type": "object", "required": [ "server_urls" ], "properties": { "server_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The server URLs. It should be configured if the server URLs are not defined in the OpenAPI spec.", "example": [ "http://localhost:8080", "http://localhost:8081" ] } } } ] } ] } ] } } } }, "responses": { "200": { "description": "API product updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The API product fields.", "oneOf": [ { "title": "Gateway API Product", "type": "object", "allOf": [ { "type": "object", "required": [ "type", "name", "linked_gateway_services" ], "properties": { "type": { "type": "string", "enum": [ "gateway" ], "default": "gateway" }, "name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "logo": { "type": "string", "description": "The base64-encoded logo image of the API product." }, "desc": { "type": "string", "description": "The description of the API product.", "example": "The Weather Insights API provides real-time and historical weather data for any location worldwide." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "auth": { "type": "object", "description": "The authentication configuration of the API product.", "additionalProperties": false, "minProperties": 1, "example": { "key-auth": { "header": "apikey", "hide_credentials": false, "query": "apikey" } }, "properties": { "key-auth": { "type": "object", "additionalProperties": false, "description": "Key authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." }, "query": { "type": "string", "default": "apikey", "description": "The query string to get the key from. Lower priority than header." }, "header": { "type": "string", "default": "apikey", "description": "The header to get the key from." } } }, "basic-auth": { "type": "object", "additionalProperties": false, "description": "Basic authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." } } }, "dcr": { "type": "object", "additionalProperties": false, "description": "DCR authentication configurations.", "required": [ "dcr_provider_id" ], "properties": { "dcr_provider_id": { "description": "ID of the DCR provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } }, "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "minItems": 1, "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "service_id": { "description": "The service template ID of the published service.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "linked_hosts": { "type": "array", "description": "Select one or more hosts configured for the gateway service to be published to the API portal. If not set, it means using all hosts of the gateway service.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "subscription_auto_approval": { "type": "boolean", "default": false, "description": "If true, the subscription is automatically approved." }, "can_view_unsubscribed": { "type": "boolean", "description": "If true, developers can view the unsubscribed API.", "default": true }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "type": "object", "properties": { "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "items": { "type": "object", "description": "The gateway group and service that the API product is linked to.", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "name": { "description": "The service name.", "example": "Weather Insights API", "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "string", "description": "The version of the published service.", "example": "1.3.2" }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "hosts": { "type": "array", "items": { "example": "weatherinsights.com", "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$" } }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "openapi_title": { "type": "string", "description": "The title of the OpenAPI file.", "example": "Weather Insights API - OpenAPI 3.0" } } } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "title": "External API Product", "type": "object", "allOf": [ { "allOf": [ { "type": "object", "required": [ "name", "type", "raw_openapi" ], "properties": { "type": { "type": "string", "description": "Type of API product.", "enum": [ "external" ], "default": "external" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "raw_openapi": { "type": "string", "minLength": 1, "description": "The content of the OpenAPI YAML file.", "example": "Raw OpenAPI spec" }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "anyOf": [ { "type": "object", "required": [ "server_url" ], "properties": { "server_url": { "deprecated": true, "type": "string", "minLength": 1, "maxLength": 4096, "description": "The server URL. It should be configured if the server URL is not defined in the OpenAPI spec.", "example": "http://localhost:8080" } } }, { "type": "object", "required": [ "server_urls" ], "properties": { "server_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The server URLs. It should be configured if the server URLs are not defined in the OpenAPI spec.", "example": [ "http://localhost:8080", "http://localhost:8081" ] } } } ] } ] }, { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "desc": { "type": "string", "description": "Description." }, "api_desc": { "type": "string", "description": "API description." }, "api_count": { "type": "number", "format": "int32", "description": "API count.", "example": 10 } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } ] }, { "type": "object", "properties": { "notifications": { "description": "Notification details.", "type": "array", "items": { "oneOf": [ { "title": "Email", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "email" ] }, "email_subject": { "type": "string", "description": "Email subject.", "example": "API7 Enterprise alert." }, "content": { "type": "string", "description": "Email content.", "example": "This is a alert testing email." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] }, { "title": "Webhook", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "webhook" ] }, "message": { "type": "string", "description": "Notification message.", "example": "This is a alert testing message." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] } ] } } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Provider Portal - API Product" ], "summary": "Patch an API product in Provider Portal", "operationId": "patchAPIProduct-ProviderPortal", "description": "IAM Action: `portal:UpdateAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "api_product_id", "description": "The unique identifier of the API product.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "API product updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The API product fields.", "oneOf": [ { "title": "Gateway API Product", "type": "object", "allOf": [ { "type": "object", "required": [ "type", "name", "linked_gateway_services" ], "properties": { "type": { "type": "string", "enum": [ "gateway" ], "default": "gateway" }, "name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "logo": { "type": "string", "description": "The base64-encoded logo image of the API product." }, "desc": { "type": "string", "description": "The description of the API product.", "example": "The Weather Insights API provides real-time and historical weather data for any location worldwide." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "auth": { "type": "object", "description": "The authentication configuration of the API product.", "additionalProperties": false, "minProperties": 1, "example": { "key-auth": { "header": "apikey", "hide_credentials": false, "query": "apikey" } }, "properties": { "key-auth": { "type": "object", "additionalProperties": false, "description": "Key authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." }, "query": { "type": "string", "default": "apikey", "description": "The query string to get the key from. Lower priority than header." }, "header": { "type": "string", "default": "apikey", "description": "The header to get the key from." } } }, "basic-auth": { "type": "object", "additionalProperties": false, "description": "Basic authentication configurations.", "properties": { "hide_credentials": { "type": "boolean", "default": false, "description": "If true, do not pass the header or query string with key to upstream services." } } }, "dcr": { "type": "object", "additionalProperties": false, "description": "DCR authentication configurations.", "required": [ "dcr_provider_id" ], "properties": { "dcr_provider_id": { "description": "ID of the DCR provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } }, "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "minItems": 1, "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "service_id": { "description": "The service template ID of the published service.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "linked_hosts": { "type": "array", "description": "Select one or more hosts configured for the gateway service to be published to the API portal. If not set, it means using all hosts of the gateway service.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "subscription_auto_approval": { "type": "boolean", "default": false, "description": "If true, the subscription is automatically approved." }, "can_view_unsubscribed": { "type": "boolean", "description": "If true, developers can view the unsubscribed API.", "default": true }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "type": "object", "properties": { "linked_gateway_services": { "type": "array", "description": "An array of gateway groups and services that the API product is linked to.", "items": { "type": "object", "description": "The gateway group and service that the API product is linked to.", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "name": { "description": "The service name.", "example": "Weather Insights API", "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "string", "description": "The version of the published service.", "example": "1.3.2" }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "hosts": { "type": "array", "items": { "example": "weatherinsights.com", "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$" } }, "updated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "openapi_title": { "type": "string", "description": "The title of the OpenAPI file.", "example": "Weather Insights API - OpenAPI 3.0" } } } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "title": "External API Product", "type": "object", "allOf": [ { "allOf": [ { "type": "object", "required": [ "name", "type", "raw_openapi" ], "properties": { "type": { "type": "string", "description": "Type of API product.", "enum": [ "external" ], "default": "external" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "raw_openapi": { "type": "string", "minLength": 1, "description": "The content of the OpenAPI YAML file.", "example": "Raw OpenAPI spec" }, "status": { "type": "string", "description": "Status of the API product.", "enum": [ "draft", "published" ], "default": "draft" }, "visibility": { "type": "string", "enum": [ "public", "logged_in" ], "default": "public", "description": "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." } } }, { "anyOf": [ { "type": "object", "required": [ "server_url" ], "properties": { "server_url": { "deprecated": true, "type": "string", "minLength": 1, "maxLength": 4096, "description": "The server URL. It should be configured if the server URL is not defined in the OpenAPI spec.", "example": "http://localhost:8080" } } }, { "type": "object", "required": [ "server_urls" ], "properties": { "server_urls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 4096 }, "description": "The server URLs. It should be configured if the server URLs are not defined in the OpenAPI spec.", "example": [ "http://localhost:8080", "http://localhost:8081" ] } } } ] } ] }, { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "desc": { "type": "string", "description": "Description." }, "api_desc": { "type": "string", "description": "API description." }, "api_count": { "type": "number", "format": "int32", "description": "API count.", "example": 10 } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } ] }, { "type": "object", "properties": { "notifications": { "description": "Notification details.", "type": "array", "items": { "oneOf": [ { "title": "Email", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "email" ] }, "email_subject": { "type": "string", "description": "Email subject.", "example": "API7 Enterprise alert." }, "content": { "type": "string", "description": "Email content.", "example": "This is a alert testing email." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] }, { "title": "Webhook", "type": "object", "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the notification.", "enum": [ "webhook" ] }, "message": { "type": "string", "description": "Notification message.", "example": "This is a alert testing message." } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } } } } ] } ] } } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Provider Portal - API Product" ], "summary": "Delete an API product in Provider Portal", "operationId": "deleteAPIProduct-ProviderPortal", "description": "IAM Action: `portal:DeleteAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "api_product_id", "description": "The unique identifier of the API product.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/api_products/{api_product_id}/subscriptions": { "get": { "tags": [ "Provider Portal - API Product" ], "summary": "List all subscriptions in Provider Portal for an API product", "operationId": "listSubscriptions", "description": "IAM Action: `portal:GetAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "api_product_id", "description": "The unique identifier of the API product.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "subscribed_at", "enum": [ "developer_name", "subscribed_at" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of subscriptions.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of Developer user.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the subscription." }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "developer_id": { "type": "string" }, "developer_name": { "type": "string" }, "subscribed_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "application_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "application_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "api_product_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "api_product_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "status": { "type": "string", "enum": [ "unsubscribed", "wait_for_approval", "subscribed" ] } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/api_products/{api_product_id}/subscriptions/{subscription_id}": { "delete": { "tags": [ "Provider Portal - API Product" ], "summary": "Cancel a subscription in Provider Portal for an API product", "operationId": "cancelSubscription", "description": "IAM Action: `portal:UpdateAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "api_product_id", "description": "The unique identifier of the API product.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "subscription_id", "description": "the unique identifier of the subscription.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/api_products/{api_product_id}/notification_histories": { "get": { "tags": [ "Provider Portal - API Product" ], "summary": "List all notification histories for an API product", "description": "IAM Action: `portal:GetAPIProduct`, Resource: `arn:api7:portal:portal/%s/apiproduct/%s`", "parameters": [ { "name": "api_product_id", "description": "The unique identifier of the API product.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "notification_type", "description": "The type of the notification.", "in": "query", "schema": { "type": "string", "enum": [ "email", "webhook" ] } }, { "name": "event", "description": "Notification trigger.", "in": "query", "schema": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] } }, { "name": "contact_point_id", "description": "The contact point ID of the notification.", "in": "query", "schema": { "type": "string", "example": "6c97bc5f-3356-41f5-894c-c88df5389bd2" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Order to list the notifications by.", "schema": { "type": "string", "default": "notified_at", "enum": [ "notified_at" ] } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of API product notification histories.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of notification.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "notified_at": { "description": "The notification sent timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "notification": { "oneOf": [ { "title": "Email", "required": [ "type", "subject", "content" ], "properties": { "type": { "description": "Type of notification.", "enum": [ "email" ] }, "subject": { "type": "string", "description": "The email subject.", "example": "API7 Notification" }, "content": { "type": "string", "description": "The email content.", "example": "This is a test notification." } } }, { "title": "Webhook", "required": [ "type", "message" ], "properties": { "type": { "description": "Type of notification.", "enum": [ "webhook" ] }, "message": { "type": "string", "description": "The notification message.", "example": "This is a test notification." } } } ], "type": "object", "description": "The associated notification configurations.", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "event": { "type": "string", "description": "Notification trigger.", "enum": [ "subscription_approval_created", "subscription_approval_accepted", "subscription_approval_rejected", "subscription_cancelled" ] }, "contact_points": { "type": "array", "description": "An array of contact points.", "items": { "type": "object", "properties": { "id": { "description": "ID of the contact point.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "Name of the contact point.", "type": "string", "example": "cp-docs-test" } } } } } }, "developer_id": { "example": "7e4d29f5-a4bc-4e0d-9c02-5a0d8e1c3427", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256 }, "developer_name": { "type": "string", "description": "Developer name.", "example": "johndoe" }, "application_id": { "description": "Application ID.", "example": "default" }, "application_name": { "type": "string", "description": "Application name.", "example": "Weather Insights API" }, "approval_id": { "description": "Approval ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "subscription_id": { "description": "Subscription ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "notification_logs": { "type": "array", "description": "Logs of notifications that were sent.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "contact_point_name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test" }, "resource_type": { "type": "string", "description": "Type of notification.", "enum": [ "alert_policy", "api_product_notification" ] }, "resource_id": { "description": "The resource ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "resource_name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "description": "Notification sending status.", "enum": [ "success", "failed" ], "example": "failed" }, "send_time": { "type": "integer", "example": 1759649130, "description": "The time when the notification is sent." }, "request": { "type": "string", "description": "Request information.", "example": "{\"from\": \"test.send@api7.ai\", \"to\": \"test.receive@api7.ai\", \"subject\": \"API7 Notification\", \"content\": \"This is a test notification.\"}" }, "response": { "type": "string", "description": "Response from the server.", "example": "450 The domain must be verified in your account to send emails." } } } }, "resource_id": { "description": "Resource ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "resource_name": { "description": "Resource name.", "example": "Weather Insights API", "type": "string", "minLength": 1, "maxLength": 100 } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/developers": { "get": { "tags": [ "Developer" ], "summary": "List Developers", "description": "IAM Action: `portal:GetDeveloper`, Resource: `arn:api7:portal:portal/%s/developer/%s`", "operationId": "listDeveloperUsers", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order developers by.", "schema": { "type": "string", "default": "last_active_at", "enum": [ "last_active_at", "created_at" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of developer users.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of Developer user.", "items": { "allOf": [ { "type": "object", "properties": { "username": { "type": "string", "description": "Unique developer username.", "example": "dev1" }, "name": { "type": "string", "description": "Developer name.", "example": "dev one" }, "last_active_at": { "type": "integer", "description": "Developer last active timestamp.", "example": 1742288233 } } }, { "type": "object", "properties": { "id": { "description": "Developer ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "portal_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "state": { "type": "string", "description": "The state of the member.\n- Pending: The user is pending approval.\n- Active: The user had been approved.", "enum": [ "Pending", "Active" ] } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/developers/{developer_external_id}": { "delete": { "tags": [ "Developer" ], "summary": "Delete a developer", "description": "IAM Action: `portal:DeleteDeveloper`, Resource: `arn:api7:portal:portal/%s/developer/%s`", "operationId": "deleteDeveloperUser", "parameters": [ { "name": "developer_external_id", "in": "path", "required": true, "description": "Developer external ID.", "schema": { "type": "string", "example": "dev1" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/portal/monitor/query": { "get": { "tags": [ "Monitoring" ], "summary": "Get provider portal monitoring data at a single point in time", "description": "See Prometheus [instant queries](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries) for more information.", "operationId": "portalMonitorQuery", "parameters": [ { "name": "query", "description": "Prometheus expression query string.", "in": "query", "required": true, "schema": { "type": "string", "example": "apisix" } }, { "name": "time", "description": "Evaluation timestamp. Accepts either a Unix timestamp or an RFC3339 timestamp.", "in": "query", "required": false, "schema": { "oneOf": [ { "title": "Unix Timestamp", "type": "integer", "example": 1718531400 }, { "title": "RFC3339 Timestamp", "type": "string", "format": "date-time", "example": "2025-06-17T12:00:00Z" } ] } }, { "name": "timeout", "description": "Evaluation timeout, either as:\n- A float number in seconds (e.g. `2.5`)\n- A duration string (e.g. `5s`, `1.5m`) in Prometheus-style format.\n", "in": "query", "required": false, "schema": { "oneOf": [ { "title": "Float", "type": "number", "format": "float", "example": 2.5 }, { "title": "Duration", "type": "string", "example": "1.5m" } ] } }, { "name": "limit", "description": "Maximum number of returned series. 0 means disabled.", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "The Prometheus proxy response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "The Prometheus raw data.", "additionalProperties": true, "example": { "status": "success", "data": { "resultType": "matrix", "result": [ { "metric": { "label": "xxx" }, "values": [ [ 1684740675, 1 ], [ 1684740690, 2 ] ] } ] } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/portal/monitor/query_range": { "get": { "tags": [ "Monitoring" ], "summary": "Get provider portal monitoring data over a range of time", "description": "See Prometheus [range queries](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) for more information.", "operationId": "portalMonitorQueryRange", "parameters": [ { "name": "query", "description": "Prometheus expression query string.", "in": "query", "required": true, "schema": { "type": "string", "example": "apisix" } }, { "name": "start", "description": "Start timestamp, inclusive. Accepts either a Unix timestamp or an RFC3339 timestamp.", "in": "query", "required": true, "schema": { "oneOf": [ { "title": "Unix Timestamp", "type": "integer", "example": 1718531400 }, { "title": "RFC3339 Timestamp", "type": "string", "format": "date-time", "example": "2025-06-16T12:00:00Z" } ] } }, { "name": "end", "description": "End timestamp, inclusive. Accepts either a Unix timestamp or an RFC3339 timestamp.", "in": "query", "required": true, "schema": { "oneOf": [ { "title": "Unix Timestamp", "type": "integer", "example": 1718531400 }, { "title": "RFC3339 Timestamp", "type": "string", "format": "date-time", "example": "2025-06-17T12:00:00Z" } ] } }, { "name": "step", "description": "Query resolution step width, either as:\n- a float number in seconds (e.g. `15.5`), or\n- a duration string (e.g. `15s`, `1m`, `2h`) in Prometheus-style duration format.\n", "in": "query", "required": true, "schema": { "oneOf": [ { "title": "Float", "type": "number", "format": "float", "example": 15.5 }, { "title": "Duration", "type": "string", "example": "15s" } ] } }, { "name": "timeout", "description": "Evaluation timeout, either as:\n- A float number in seconds (e.g. `2.5`)\n- A duration string (e.g. `5s`, `1.5m`) in Prometheus-style format.\n", "in": "query", "required": false, "schema": { "oneOf": [ { "title": "Float", "type": "number", "format": "float", "example": 2.5 }, { "title": "Duration", "type": "string", "example": "1.5m" } ] } }, { "name": "limit", "description": "Maximum number of returned series. 0 means disabled.", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "The Prometheus proxy response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "The Prometheus raw data.", "additionalProperties": true, "example": { "status": "success", "data": { "resultType": "matrix", "result": [ { "metric": { "label": "xxx" }, "values": [ [ 1684740675, 1 ], [ 1684740690, 2 ] ] } ] } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/portals": { "get": { "tags": [ "Provider Portal - Portal Instance" ], "summary": "List all portal instances", "operationId": "listPortals", "description": "IAM Action: `portal:ListPortals`, Resource: `arn:api7:portal:portal/*`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Portal list response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "description": "An array of portal instances.", "type": "array", "items": { "description": "The portal instance with management fields.", "allOf": [ { "description": "The portal instance description.", "type": "object", "required": [ "name", "public_url" ], "properties": { "name": { "description": "Portal instance name.", "example": "Developer Portal", "type": "string", "minLength": 1, "maxLength": 100 }, "labels": { "description": "Labels of the portal instance.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "public_url": { "type": "string", "minLength": 1, "format": "url", "description": "Portal instance public URL.", "example": "https://portal.example.com" } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "post": { "tags": [ "Provider Portal - Portal Instance" ], "summary": "Create a portal instance", "operationId": "createPortal", "description": "IAM Action: `portal:CreatePortal`, Resource: `arn:api7:portal:portal/*`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "The portal instance description.", "type": "object", "required": [ "name", "public_url" ], "properties": { "name": { "description": "Portal instance name.", "example": "Developer Portal", "type": "string", "minLength": 1, "maxLength": 100 }, "labels": { "description": "Labels of the portal instance.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "public_url": { "type": "string", "minLength": 1, "format": "url", "description": "Portal instance public URL.", "example": "https://portal.example.com" } } } } } }, "responses": { "200": { "description": "Portal response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The portal instance with management fields.", "allOf": [ { "description": "The portal instance description.", "type": "object", "required": [ "name", "public_url" ], "properties": { "name": { "description": "Portal instance name.", "example": "Developer Portal", "type": "string", "minLength": 1, "maxLength": 100 }, "labels": { "description": "Labels of the portal instance.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "public_url": { "type": "string", "minLength": 1, "format": "url", "description": "Portal instance public URL.", "example": "https://portal.example.com" } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/portals/{portal_id}": { "get": { "tags": [ "Provider Portal - Portal Instance" ], "summary": "Get a portal instance", "operationId": "getPortal", "description": "IAM Action: `portal:GetPortal`, Resource: `arn:api7:portal:portal/%s`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Portal response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The portal instance with management fields.", "allOf": [ { "description": "The portal instance description.", "type": "object", "required": [ "name", "public_url" ], "properties": { "name": { "description": "Portal instance name.", "example": "Developer Portal", "type": "string", "minLength": 1, "maxLength": 100 }, "labels": { "description": "Labels of the portal instance.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "public_url": { "type": "string", "minLength": 1, "format": "url", "description": "Portal instance public URL.", "example": "https://portal.example.com" } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Provider Portal - Portal Instance" ], "summary": "Update a portal instance", "operationId": "updatePortal", "description": "IAM Action: `portal:UpdatePortal`, Resource: `arn:api7:portal:portal/%s`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "The portal instance description.", "type": "object", "required": [ "name", "public_url" ], "properties": { "name": { "description": "Portal instance name.", "example": "Developer Portal", "type": "string", "minLength": 1, "maxLength": 100 }, "labels": { "description": "Labels of the portal instance.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "public_url": { "type": "string", "minLength": 1, "format": "url", "description": "Portal instance public URL.", "example": "https://portal.example.com" } } } } } }, "responses": { "200": { "description": "Portal response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The portal instance with management fields.", "allOf": [ { "description": "The portal instance description.", "type": "object", "required": [ "name", "public_url" ], "properties": { "name": { "description": "Portal instance name.", "example": "Developer Portal", "type": "string", "minLength": 1, "maxLength": 100 }, "labels": { "description": "Labels of the portal instance.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "public_url": { "type": "string", "minLength": 1, "format": "url", "description": "Portal instance public URL.", "example": "https://portal.example.com" } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Provider Portal - Portal Instance" ], "summary": "Delete a portal instance", "operationId": "deletePortal", "description": "IAM Action: `portal:DeletePortal`, Resource: `arn:api7:portal:portal/%s`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/portal/tokens": { "post": { "tags": [ "Provider Portal - Portal Token" ], "summary": "Create a portal token", "operationId": "createPortalToken", "description": "IAM Action: `portal:CreatePortalToken`, Resource: `arn:api7:portal:portal/%s/token/*`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Create a portal token.", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 256, "description": "The portal token name.", "example": "my-portal-token" }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the portal token. `0` means the token will not expire.", "example": 1752288235 } } } } } }, "responses": { "200": { "description": "Portal token created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "id": { "description": "The portal token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 256, "description": "The portal token name.", "example": "my-portal-token" }, "portal_id": { "description": "The portal ID that this token belongs to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The time when a portal token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a portal token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the portal token. `0` means the token will not expire.", "example": 1752288235 }, "last_used_at": { "description": "The last time when the portal token is used.", "type": "integer", "minimum": 0, "example": 1742288235 } } }, { "type": "object", "properties": { "token": { "type": "string", "description": "The created portal token value.", "example": "a7prt-gyb4v2Ryc2xfh9w707Z7r6IW3E0c1D7hu7x9ZT8Fxxxxx3G4Q9-5b101b5c7fc34e988f1ff9979cc191e1" } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Provider Portal - Portal Token" ], "summary": "List all portal tokens", "operationId": "listPortalTokens", "description": "IAM Action: `portal:GetPortalToken`, Resource: `arn:api7:portal:portal/%s/token/*`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "order_by", "in": "query", "description": "Index to order the portal tokens by.", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "updated_at", "expires_at" ] } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of portal tokens.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of portal tokens.", "items": { "type": "object", "properties": { "id": { "description": "The portal token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 256, "description": "The portal token name.", "example": "my-portal-token" }, "portal_id": { "description": "The portal ID that this token belongs to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The time when a portal token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a portal token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the portal token. `0` means the token will not expire.", "example": 1752288235 }, "last_used_at": { "description": "The last time when the portal token is used.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/portal/tokens/{portal_token_id}": { "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_token_id", "description": "The unique identifier of the portal token.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "get": { "tags": [ "Provider Portal - Portal Token" ], "summary": "Get a portal token", "operationId": "getPortalToken", "description": "IAM Action: `portal:GetPortalToken`, Resource: `arn:api7:portal:portal/%s/token/*`", "responses": { "200": { "description": "Successfully retrieved the portal token.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The portal token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 256, "description": "The portal token name.", "example": "my-portal-token" }, "portal_id": { "description": "The portal ID that this token belongs to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The time when a portal token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a portal token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the portal token. `0` means the token will not expire.", "example": 1752288235 }, "last_used_at": { "description": "The last time when the portal token is used.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Provider Portal - Portal Token" ], "summary": "Update a portal token", "operationId": "updatePortalToken", "description": "IAM Action: `portal:UpdatePortalToken`, Resource: `arn:api7:portal:portal/%s/token/*`", "requestBody": { "content": { "application/json": { "schema": { "description": "Update a portal token.", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 256, "description": "The portal token name.", "example": "my-portal-token" } } } } } }, "responses": { "200": { "description": "Successfully retrieved the portal token.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The portal token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 256, "description": "The portal token name.", "example": "my-portal-token" }, "portal_id": { "description": "The portal ID that this token belongs to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The time when a portal token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a portal token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the portal token. `0` means the token will not expire.", "example": 1752288235 }, "last_used_at": { "description": "The last time when the portal token is used.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Provider Portal - Portal Token" ], "summary": "Delete a portal token", "operationId": "deletePortalToken", "description": "IAM Action: `portal:DeletePortalToken`, Resource: `arn:api7:portal:portal/%s/token/*`", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/portal/tokens/{portal_token_id}/regenerate": { "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "portal_token_id", "description": "The unique identifier of the portal token.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "put": { "tags": [ "Provider Portal - Portal Token" ], "summary": "Regenerate a portal token", "operationId": "regeneratePortalToken", "description": "IAM Action: `portal:UpdatePortalToken`, Resource: `arn:api7:portal:portal/%s/token/*`", "requestBody": { "content": { "application/json": { "schema": { "description": "Regenerate a portal token.", "type": "object", "required": [ "expires_at" ], "properties": { "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the portal token. `0` means the token will not expire.", "example": 1752288235 } } } } } }, "responses": { "200": { "description": "Portal token created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "id": { "description": "The portal token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 256, "description": "The portal token name.", "example": "my-portal-token" }, "portal_id": { "description": "The portal ID that this token belongs to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The time when a portal token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a portal token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the portal token. `0` means the token will not expire.", "example": 1752288235 }, "last_used_at": { "description": "The last time when the portal token is used.", "type": "integer", "minimum": 0, "example": 1742288235 } } }, { "type": "object", "properties": { "token": { "type": "string", "description": "The created portal token value.", "example": "a7prt-gyb4v2Ryc2xfh9w707Z7r6IW3E0c1D7hu7x9ZT8Fxxxxx3G4Q9-5b101b5c7fc34e988f1ff9979cc191e1" } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/global_rules": { "post": { "tags": [ "Global Rule" ], "summary": "Create a global rule on a gateway group", "operationId": "createGlobalRule", "description": "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.\n**Required IAM Permission:** Action `gateway:CreateGlobalPluginRule`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The global rule description.", "type": "object", "required": [ "plugins" ], "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } } } }, "responses": { "200": { "description": "Global rule created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The global rule with management fields.", "allOf": [ { "description": "The global rule description.", "type": "object", "required": [ "plugins" ], "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "id": { "description": "Name of the plugin.", "type": "string", "minLength": 1, "maxLength": 64, "example": "key-auth" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Global Rule" ], "summary": "List all global rules on a gateway group", "operationId": "listGlobalRules", "description": "List global plugin rules configured for the gateway group. This helps audit request-wide policies and understand which plugins are enforced universally.\n**Required IAM Permission:** Action `gateway:GetGlobalPluginRule`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of global rules.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of global rules.", "items": { "description": "The global rule with management fields.", "allOf": [ { "description": "The global rule description.", "type": "object", "required": [ "plugins" ], "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "id": { "description": "Name of the plugin.", "type": "string", "minLength": 1, "maxLength": 64, "example": "key-auth" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/global_rules/{global_rule_id}": { "get": { "tags": [ "Global Rule" ], "summary": "Get a global rule on a gateway group", "operationId": "getGlobalRule", "description": "Retrieve one global rule in the gateway group, including its plugin configuration and execution settings.\n**Required IAM Permission:** Action `gateway:GetGlobalPluginRule`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "global_rule_id", "description": "The unique identifier of the global rule.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the global rule.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The global rule with management fields.", "allOf": [ { "description": "The global rule description.", "type": "object", "required": [ "plugins" ], "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "id": { "description": "Name of the plugin.", "type": "string", "minLength": 1, "maxLength": 64, "example": "key-auth" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Global Rule" ], "summary": "Update a global rule on a gateway group", "operationId": "putGlobalRule", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdateGlobalPluginRule`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "global_rule_id", "description": "The unique identifier of the global rule.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The global rule description.", "type": "object", "required": [ "plugins" ], "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } } } }, "responses": { "200": { "description": "Global rule updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The global rule with management fields.", "allOf": [ { "description": "The global rule description.", "type": "object", "required": [ "plugins" ], "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "properties": { "id": { "description": "Name of the plugin.", "type": "string", "minLength": 1, "maxLength": 64, "example": "key-auth" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Global Rule" ], "summary": "Delete a global rule on a gateway group", "operationId": "deleteGlobalRule", "description": "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.\n**Required IAM Permission:** Action `gateway:DeleteGlobalPluginRule`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "global_rule_id", "description": "The unique identifier of the global rule.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/plugin_metadata": { "get": { "tags": [ "Plugin Metadata" ], "summary": "List all plugin metadata on a gateway group", "operationId": "listPluginMetadata", "description": "List plugin metadata objects configured in the gateway group. Plugin metadata provides shared settings for a plugin type across all its instances.\n**Required IAM Permission:** Action `gateway:GetPluginMetadata`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved all plugin metadata entries for the gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "Plugin name to metadata map.", "additionalProperties": { "description": "Plugin metadata.", "type": "object", "example": { "disabled_labels": { "status": [ "code" ] } } }, "example": { "prometheus": { "disabled_labels": { "status": [ "code" ] } }, "syslog": { "log_format": { "@timestamp": "$time_iso8601", "client_ip": "$remote_addr", "host": "$host", "route_id": "$route_id" } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/plugin_metadata/{plugin_name}": { "get": { "tags": [ "Plugin Metadata" ], "summary": "Get a plugin metadata on a gateway group", "operationId": "getPluginMetadata", "description": "Retrieve metadata for a specific plugin type in the gateway group. You can optionally request default metadata values for comparison.\n**Required IAM Permission:** Action `gateway:GetPluginMetadata`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "plugin_name", "description": "Name of the plugin.", "in": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true }, { "name": "return_default", "in": "query", "schema": { "type": "boolean", "description": "When set to true, the default value is returned when plugin metadata is not found.", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved or modified the plugin metadata.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "Plugin metadata.", "type": "object", "example": { "disabled_labels": { "status": [ "code" ] } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Plugin Metadata" ], "summary": "Update a plugin metadata on a gateway group", "operationId": "putPluginMetadata", "description": "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.\n**Required IAM Permission:** Action `gateway:UpdatePluginMetadata`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "plugin_name", "description": "Name of the plugin.", "in": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "description": "Plugin metadata.", "type": "object", "example": { "disabled_labels": { "status": [ "code" ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the plugin metadata.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "Plugin metadata.", "type": "object", "example": { "disabled_labels": { "status": [ "code" ] } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Plugin Metadata" ], "summary": "Delete a plugin metadata on a gateway group", "operationId": "deletePluginMetadata", "description": "Delete metadata for a specific plugin type in the gateway group and revert to plugin defaults where applicable. Validate downstream plugin behavior after removal.\n**Required IAM Permission:** Action `gateway:DeletePluginMetadata`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "plugin_name", "description": "Name of the plugin.", "in": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/plugin_metadata/{plugin_name}/default": { "get": { "tags": [ "Plugin Metadata" ], "summary": "Get the default value of a plugin metadata", "operationId": "getPluginMetadataDefaultValue", "parameters": [ { "name": "plugin_name", "description": "Name of the plugin.", "in": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the default plugin metadata schema.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "Plugin metadata.", "type": "object", "example": {} } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/plugins": { "get": { "tags": [ "Plugin" ], "summary": "Get all plugin schemas and priorities", "operationId": "listPluginDetail", "parameters": [ { "name": "subsystem", "in": "query", "schema": { "type": "string", "default": "http", "enum": [ "http", "stream" ], "example": "stream" }, "description": "Type to filter the plugin list. `http` will only show L7 plugins and `stream` will only show L4 plugins." } ], "responses": { "200": { "description": "Successfully retrieved the detailed plugin schemas including configuration options.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": { "type": "object", "properties": { "schema": { "type": "object" }, "consumer_schema": { "type": "object" }, "metadata_schema": { "type": "object" }, "type": { "type": "string" }, "scope": { "type": "string" }, "priority": { "type": "integer" } } }, "example": { "acl": { "schema": { "$comment": "this is a mark for our injected plugin schema", "allOf": [ { "if": { "properties": { "external_user_label_field_parser": { "const": "segmented_text" } }, "required": [ "external_user_label_field_parser" ] }, "then": { "required": [ "external_user_label_field_separator" ] } } ], "anyOf": [ { "required": [ "allow_labels" ] }, { "required": [ "deny_labels" ] } ], "properties": { "_meta": { "properties": { "disable": { "type": "boolean" }, "error_response": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "filter": { "description": "filter determines whether the plugin needs to be executed at runtime", "type": "array" }, "pre_function": { "description": "function to be executed in each phase before execution of plugins. The pre_function will have access to two arguments: `conf` and `ctx`.", "type": "string" }, "priority": { "description": "priority of plugins by customized order", "type": "integer" } }, "type": "object" }, "allow_labels": { "minProperties": 1, "patternProperties": { ".*": { "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "type": "object" }, "deny_labels": { "minProperties": 1, "patternProperties": { ".*": { "items": { "type": "string" }, "minItems": 1, "type": "array" } }, "type": "object" }, "external_user_label_field": { "default": "groups", "type": "string" }, "external_user_label_field_key": { "minLength": 1, "type": "string" }, "external_user_label_field_parser": { "enum": [ "segmented_text", "json", "table" ], "type": "string" }, "external_user_label_field_separator": { "description": "The separator(regex) of the segmented_text parser", "minLength": 1, "type": "string" }, "rejected_code": { "default": 403, "minimum": 200, "type": "integer" }, "rejected_msg": { "type": "string" } }, "type": "object" }, "priority": 2410 }, "ai-aliyun-content-moderation": { "schema": { "$comment": "this is a mark for our injected plugin schema", "encrypt_fields": [ "access_key_secret" ], "properties": { "_meta": { "additionalProperties": false, "properties": { "disable": { "type": "boolean" }, "error_response": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "filter": { "description": "filter determines whether the plugin needs to be executed at runtime", "type": "array" }, "pre_function": { "description": "function to be executed in each phase before execution of plugins. The pre_function will have access to two arguments: `conf` and `ctx`.", "type": "string" }, "priority": { "description": "priority of plugins by customized order", "type": "integer" } }, "type": "object" }, "access_key_id": { "minLength": 1, "type": "string" }, "access_key_secret": { "minLength": 1, "type": "string" }, "check_request": { "default": true, "type": "boolean" }, "check_response": { "default": false, "type": "boolean" }, "deny_code": { "default": 200, "type": "number" }, "deny_message": { "type": "string" }, "endpoint": { "minLength": 1, "type": "string" }, "region_id": { "minLength": 1, "type": "string" }, "request_check_length_limit": { "default": 2000, "type": "number" }, "request_check_service": { "default": "llm_query_moderation", "minLength": 1, "type": "string" }, "response_check_length_limit": { "default": 5000, "type": "number" }, "response_check_service": { "default": "llm_response_moderation", "minLength": 1, "type": "string" }, "risk_level_bar": { "default": "high", "enum": [ "none", "low", "medium", "high", "max" ], "type": "string" }, "ssl_verify": { "default": true, "type": "boolean" }, "stream_check_cache_size": { "default": 128, "description": "max characters per moderation batch in realtime mode", "minimum": 1, "type": "integer" }, "stream_check_interval": { "default": 3, "description": "seconds between batch checks in realtime mode", "minimum": 0.1, "type": "number" }, "stream_check_mode": { "default": "final_packet", "description": "realtime: batched checks during streaming | final_packet: append risk_level at end\n", "enum": [ "realtime", "final_packet" ], "type": "string" }, "timeout": { "default": 10000, "description": "timeout in milliseconds", "minimum": 1, "type": "integer" } }, "required": [ "endpoint", "region_id", "access_key_id", "access_key_secret" ], "type": "object" }, "priority": 1029 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/apisix/admin/plugins/list": { "get": { "tags": [ "Plugin" ], "summary": "List all plugin names", "operationId": "listPlugins", "parameters": [ { "name": "has_metadata", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, show plugin names where the plugins have metadata." }, { "name": "subsystem", "in": "query", "schema": { "type": "string", "default": "http", "enum": [ "http", "stream" ], "example": "stream" }, "description": "Type to filter the plugin list. `http` will only show L7 plugins and `stream` will only show L4 plugins." } ], "responses": { "200": { "description": "Successfully retrieved the list of available plugin names.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plugin name." }, "example": [ "ip-restriction", "limit-conn", "mqtt-proxy", "prometheus", "syslog" ] } } } } } } }, "/apisix/admin/plugins/{plugin_name}": { "get": { "tags": [ "Plugin" ], "summary": "Get schema definition of a plugin", "description": "Get schema definition of a plugin, including plugin [meta](/apisix/reference/plugin-common-configurations) properties and plugin properties.\nThe endpoint returns the same response as the `/apisix/admin/schema/plugins/{plugin_name}` endpoint when `scope` is not set.\n", "operationId": "getPluginAllProperties", "parameters": [ { "name": "plugin_name", "description": "Name of the plugin.", "in": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true }, { "name": "scope", "description": "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.\n", "in": "query", "schema": { "type": "string", "enum": [ "all" ] } }, { "name": "subsystem", "in": "query", "schema": { "type": "string", "default": "http", "enum": [ "http", "stream" ], "example": "stream" }, "description": "Type to filter the plugin list. `http` will only show L7 plugins and `stream` will only show L4 plugins." } ], "responses": { "200": { "description": "Successfully retrieved the JSON schema for the specified plugin.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The plugin schema definition.", "type": "object", "example": { "$comment": "this is a mark for our injected plugin schema", "properties": { "_meta": { "properties": { "disable": { "type": "boolean" }, "error_response": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "filter": { "description": "filter determines whether the plugin needs to be executed at runtime", "type": "array" }, "pre_function": { "description": "function to be executed in each phase before execution of plugins. The pre_function will have access to two arguments: `conf` and `ctx`.", "type": "string" }, "priority": { "description": "priority of plugins by customized order", "type": "integer" } }, "type": "object" }, "prefer_name": { "default": false, "type": "boolean" } }, "type": "object" } } } } ] } } } } } } }, "/apisix/admin/schema/{resource_name}": { "get": { "tags": [ "Schema" ], "summary": "Get schema by resource name", "operationId": "getResourceSchema", "description": "Get the schema definition for a specific resource type by name. This is useful when rendering dynamic forms or validating resource-specific request payloads.", "parameters": [ { "name": "resource_name", "description": "Name of the resource.", "in": "path", "required": true, "example": "consumer", "schema": { "minimum": 1, "type": "string", "enum": [ "service", "upstream", "stream_service", "stream_upstream", "route", "consumer", "consumer_credential", "global_rule", "ssl", "vault_secret", "aws_secret", "kubernetes_secret", "plugin_metadata", "stream_route" ] } } ], "responses": { "200": { "description": "Successfully retrieved the schema for the specified core resource.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "example": { "description": "The consumer description.", "properties": { "desc": { "description": "The object description.", "maxLength": 65536, "type": "string" }, "labels": { "additionalProperties": { "maxLength": 65536, "minLength": 1, "pattern": "^.+$", "type": "string" }, "example": { "keyA": "valueA", "keyB": "valueB" }, "type": "object" }, "plugins": { "description": "The key-value pairs which represent the plugins attached on the object.", "type": "object" }, "username": { "maxLength": 512, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-]+$", "type": "string" } }, "required": [ "username" ], "type": "object" } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } }, "example": { "value": {}, "error_msg": "not found schema: license" } } } } } } }, "/apisix/admin/schema/plugins/{plugin_name}": { "get": { "tags": [ "Schema", "Plugin" ], "summary": "Get schema definition of a plugin", "description": "Get schema definition of a plugin, including plugin [meta](/apisix/reference/plugin-common-configurations) properties and plugin properties.", "operationId": "getPluginSchema", "parameters": [ { "name": "plugin_name", "description": "Name of the plugin.", "in": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true }, { "name": "subsystem", "in": "query", "schema": { "type": "string", "default": "http", "enum": [ "http", "stream" ], "example": "stream" }, "description": "Type to filter the plugin list. `http` will only show L7 plugins and `stream` will only show L4 plugins." } ], "responses": { "200": { "description": "Successfully retrieved the JSON schema for the specified plugin.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The plugin schema definition.", "type": "object", "example": { "$comment": "this is a mark for our injected plugin schema", "properties": { "_meta": { "properties": { "disable": { "type": "boolean" }, "error_response": { "oneOf": [ { "type": "string" }, { "type": "object" } ] }, "filter": { "description": "filter determines whether the plugin needs to be executed at runtime", "type": "array" }, "pre_function": { "description": "function to be executed in each phase before execution of plugins. The pre_function will have access to two arguments: `conf` and `ctx`.", "type": "string" }, "priority": { "description": "priority of plugins by customized order", "type": "integer" } }, "type": "object" }, "prefer_name": { "default": false, "type": "boolean" } }, "type": "object" } } } } ] } } } } } } }, "/apisix/admin/variables": { "get": { "tags": [ "Variables" ], "summary": "Get all variables", "description": "List all APISIX variables (including built-in NGINX variables) that can be used in route matching conditions and plugin configurations.", "responses": { "200": { "description": "Successfully retrieved the list of available APISIX variables.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The APISIX variable list.", "type": "array", "items": { "description": "The APISIX variable definition.", "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The variable name.", "type": "string", "minLength": 1, "maxLength": 128, "enum": [ "arg_", "args", "balancer_ip", "balancer_port", "binary_remote_addr", "body_bytes_sent", "bytes_received", "bytes_sent", "connection", "connection_requests", "connection_time", "consumer_name", "content_length", "content_type", "cookie_", "document_root", "document_uri", "graphql_name", "graphql_operation", "graphql_root_fields", "host", "hostname", "http2", "http_", "https", "invalid_referer", "is_args", "msec", "nginx_version", "pid", "pipe", "query_string", "realpath_root", "remote_addr", "remote_port", "remote_user", "request", "request_body", "request_body_file", "request_completion", "request_filename", "request_id", "request_length", "request_method", "request_time", "request_uri", "route_id", "route_name", "scheme", "sent_http_", "sent_trailer_", "server_addr", "server_name", "server_port", "server_protocol", "service_id", "service_name", "ssl_alpn_protocol", "ssl_cipher", "ssl_ciphers", "ssl_client_cert", "ssl_client_escaped_cert", "ssl_client_fingerprint", "ssl_client_i_dn", "ssl_client_i_dn_legacy", "ssl_client_raw_cert", "ssl_client_s_dn", "ssl_client_s_dn_legacy", "ssl_client_serial", "ssl_client_v_end", "ssl_client_v_remain", "ssl_client_v_start", "ssl_client_verify", "ssl_curve", "ssl_curves", "ssl_early_data", "ssl_protocol", "ssl_server_name", "ssl_session_id", "ssl_session_reused", "status", "tcpinfo_rcv_space", "tcpinfo_rtt", "tcpinfo_rttvar", "tcpinfo_snd_cwnd", "time_iso8601", "time_local", "uri" ] }, "description": { "description": "The variable description.", "type": "string", "maxLength": 65536, "example": "Object description." } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/instances": { "get": { "tags": [ "Gateway Instance" ], "summary": "List all gateway instances of all gateway groups", "operationId": "listAllGatewayInstances", "description": "IAM Action: `gateway:GetGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } }, { "name": "order_by", "in": "query", "description": "Index to order gateway instances by.", "schema": { "type": "string", "default": "last_heartbeat_time", "enum": [ "created_at", "last_heartbeat_time" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Healthy", "OutOfSync", "LostConnection", "Offline" ] }, "description": "The value of the instance status." }, { "name": "compatibility", "in": "query", "schema": { "type": "string", "enum": [ "Compatible", "Incompatible", "PartiallyCompatible" ] }, "description": "The compatibility of the gateway instance version." }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of gateway instances.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of gateway instances.", "items": { "type": "object", "required": [ "id", "hostname", "version", "ports", "last_heartbeat_time", "created_at", "status", "compatibility_report_summary" ], "properties": { "id": { "description": "The gateway instance ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "hostname": { "type": "string", "description": "The hostname of the gateway instance.", "example": "api7-ee-3-gateway-56ffbfd46d-p99fj" }, "ip": { "type": "string", "description": "The IP address of the gateway instance.", "example": "192.168.215.2" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "version": { "type": "string", "description": "The version of the gateway instance.", "example": "3.2.2" }, "ports": { "type": "array", "description": "The listening ports of the gateway instance.", "uniqueItems": true, "example": [ 9080, 9443 ], "minItems": 1, "items": { "type": "integer" } }, "last_heartbeat_time": { "description": "The time of the gateway instance's last heartbeat.", "type": "integer", "minimum": 0, "example": 1742288230 }, "last_retrieve_config_time": { "description": "The time when the gateway instance last received its configuration.", "type": "integer", "minimum": 0, "example": 1742288230 }, "to_be_deleted_at": { "nullable": true, "description": "The time to delete offline instances from the instance list.", "type": "integer", "minimum": 0, "example": 1742288230 }, "created_at": { "description": "The time of the gateway instance's first heartbeat.", "type": "integer", "minimum": 0, "example": 1742288232 }, "dataplane_certificate_expire_time": { "nullable": true, "description": "The expiration time of the certificate used for mTLS connection between the data plane and the control plane.", "type": "integer", "minimum": 0, "example": 1742288230 }, "status": { "type": "string", "description": "- `Healthy`: Indicates that the gateway instance is functioning normally. This means heartbeat signals are being received regularly, and configuration delivery is working as expected (i.e., configuration revision is in sync).\n- `OutOfSync`: Indicates that the gateway instance is sending heartbeat signals regularly, but the configuration delivery is failing (the configuration revision is out of sync).\n- `LostConnection`: Indicates the gateway instance has lost its heartbeat recently ( 2 minutes < t < 2 hours )\n- `Offline`: Indicates the gateway instance has lost its heartbeat a long ago ( 2 hours < t < 7 days )\n\nPlease note that gateway instances that have been offline for more than 7 days will be removed from the system and will not be included in this API.", "enum": [ "Healthy", "OutOfSync", "LostConnection", "Offline" ] }, "cores": { "type": "integer", "description": "The number of data plane cores.", "example": 1 }, "compatibility": { "type": "string", "description": "Compatibility between the gateway instance and the control plane, derived from the gateway version and the compatibility report together.\n- `Compatible`: The gateway runs the exact version the control plane expects. The compatibility report is disregarded in this case (there is no other version to move to), so error-level configuration issues only appear in `compatibility_report`; fix the configuration instead.\n- `PartiallyCompatible`: The gateway version is supported but not the control plane's version, with no error-level configuration issues; an upgrade is recommended.\n- `Incompatible`: The gateway version is unsupported, or it is on a supported-but-different version and reported error-level configuration issues that an upgrade may resolve. An upgrade is required.", "enum": [ "Compatible", "Incompatible", "PartiallyCompatible" ] }, "compatibility_report_summary": { "description": "Summary of the compatibility report.", "type": "object", "required": [ "error_count", "warning_count" ], "properties": { "error_count": { "type": "integer", "description": "Number of incompatible resources with error level.", "example": 0 }, "warning_count": { "type": "integer", "description": "Number of incompatible resources with warning level.", "example": 0 } } }, "compatibility_report": { "type": "array", "description": "Per-resource configuration compatibility details reported by the data plane heartbeat (e.g. plugin fields the data plane cannot accept).", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource type." }, "id": { "type": "string", "description": "Resource ID." }, "error": { "type": "string", "description": "Validation message." }, "level": { "type": "string", "enum": [ "error", "warning" ] } } } }, "running_mode": { "type": "string", "enum": [ "standard", "backup" ] } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/instances": { "get": { "tags": [ "Gateway Instance", "Gateway Group" ], "summary": "List all gateway instances on a gateway group", "operationId": "listGatewayInstances", "description": "IAM Action: `gateway:GetGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "order_by", "in": "query", "description": "Index to order gateway instances by.", "schema": { "type": "string", "default": "last_heartbeat_time", "enum": [ "created_at", "last_heartbeat_time" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "Healthy", "OutOfSync", "LostConnection", "Offline" ] }, "description": "The value of the instance status." }, { "name": "compatibility", "in": "query", "schema": { "type": "string", "enum": [ "Compatible", "Incompatible", "PartiallyCompatible" ] }, "description": "The compatibility of the gateway instance version." }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of gateway instances.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of gateway instances.", "items": { "type": "object", "required": [ "id", "hostname", "version", "ports", "last_heartbeat_time", "created_at", "status", "compatibility_report_summary" ], "properties": { "id": { "description": "The gateway instance ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "hostname": { "type": "string", "description": "The hostname of the gateway instance.", "example": "api7-ee-3-gateway-56ffbfd46d-p99fj" }, "ip": { "type": "string", "description": "The IP address of the gateway instance.", "example": "192.168.215.2" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "version": { "type": "string", "description": "The version of the gateway instance.", "example": "3.2.2" }, "ports": { "type": "array", "description": "The listening ports of the gateway instance.", "uniqueItems": true, "example": [ 9080, 9443 ], "minItems": 1, "items": { "type": "integer" } }, "last_heartbeat_time": { "description": "The time of the gateway instance's last heartbeat.", "type": "integer", "minimum": 0, "example": 1742288230 }, "last_retrieve_config_time": { "description": "The time when the gateway instance last received its configuration.", "type": "integer", "minimum": 0, "example": 1742288230 }, "to_be_deleted_at": { "nullable": true, "description": "The time to delete offline instances from the instance list.", "type": "integer", "minimum": 0, "example": 1742288230 }, "created_at": { "description": "The time of the gateway instance's first heartbeat.", "type": "integer", "minimum": 0, "example": 1742288232 }, "dataplane_certificate_expire_time": { "nullable": true, "description": "The expiration time of the certificate used for mTLS connection between the data plane and the control plane.", "type": "integer", "minimum": 0, "example": 1742288230 }, "status": { "type": "string", "description": "- `Healthy`: Indicates that the gateway instance is functioning normally. This means heartbeat signals are being received regularly, and configuration delivery is working as expected (i.e., configuration revision is in sync).\n- `OutOfSync`: Indicates that the gateway instance is sending heartbeat signals regularly, but the configuration delivery is failing (the configuration revision is out of sync).\n- `LostConnection`: Indicates the gateway instance has lost its heartbeat recently ( 2 minutes < t < 2 hours )\n- `Offline`: Indicates the gateway instance has lost its heartbeat a long ago ( 2 hours < t < 7 days )\n\nPlease note that gateway instances that have been offline for more than 7 days will be removed from the system and will not be included in this API.", "enum": [ "Healthy", "OutOfSync", "LostConnection", "Offline" ] }, "cores": { "type": "integer", "description": "The number of data plane cores.", "example": 1 }, "compatibility": { "type": "string", "description": "Compatibility between the gateway instance and the control plane, derived from the gateway version and the compatibility report together.\n- `Compatible`: The gateway runs the exact version the control plane expects. The compatibility report is disregarded in this case (there is no other version to move to), so error-level configuration issues only appear in `compatibility_report`; fix the configuration instead.\n- `PartiallyCompatible`: The gateway version is supported but not the control plane's version, with no error-level configuration issues; an upgrade is recommended.\n- `Incompatible`: The gateway version is unsupported, or it is on a supported-but-different version and reported error-level configuration issues that an upgrade may resolve. An upgrade is required.", "enum": [ "Compatible", "Incompatible", "PartiallyCompatible" ] }, "compatibility_report_summary": { "description": "Summary of the compatibility report.", "type": "object", "required": [ "error_count", "warning_count" ], "properties": { "error_count": { "type": "integer", "description": "Number of incompatible resources with error level.", "example": 0 }, "warning_count": { "type": "integer", "description": "Number of incompatible resources with warning level.", "example": 0 } } }, "compatibility_report": { "type": "array", "description": "Per-resource configuration compatibility details reported by the data plane heartbeat (e.g. plugin fields the data plane cannot accept).", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource type." }, "id": { "type": "string", "description": "Resource ID." }, "error": { "type": "string", "description": "Validation message." }, "level": { "type": "string", "enum": [ "error", "warning" ] } } } }, "running_mode": { "type": "string", "enum": [ "standard", "backup" ] } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/instances/count/{field}": { "get": { "tags": [ "Gateway Instance", "Gateway Group" ], "summary": "Count the number of gateway instances by status in a gateway group", "operationId": "countGatewayInstancesStatus", "description": "IAM Action: `gateway:GetGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID. Optional when using the gateway group admin key to authenticate.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "field", "in": "path", "required": true, "description": "Field to count by.", "schema": { "type": "string", "enum": [ "status" ] } } ], "responses": { "200": { "description": "Successfully retrieved the gateway instance count grouped by health status.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "array", "description": "An array of gateway instance count status.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Gateway status.", "example": "Healthy", "enum": [ "Healthy", "OutOfSync", "LostConnection", "Offline" ] }, "count": { "type": "integer", "description": "The number of instances.", "example": 1 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/instances/cores": { "get": { "tags": [ "Gateway Instance" ], "summary": "List gateway instances cores of all gateway groups", "operationId": "listAllGatewayInstancesCores", "description": "IAM Action: `gateway:GetGatewayInstanceCore`, Resource: `arn:api7:gateway:gatewaygroup/*`", "responses": { "200": { "description": "Successfully retrieved the current data plane core count.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "current_dp_cores": { "type": "integer", "description": "The number of current data plane cores.", "example": 1 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/instances/cores_usages/export": { "get": { "tags": [ "Gateway Instance", "Gateway Group" ], "summary": "Export the gateway instance core usage", "operationId": "exportGatewayInstancesCoresUsage", "description": "The gateway instance’s core usage is exported hourly within the specified time interval.
IAM Action: `gateway:GetGatewayInstanceCore`, Resource: `arn:api7:gateway:gatewaygroup/*`", "parameters": [ { "name": "begin_at", "in": "query", "required": true, "description": "The start time to export the gateway instance core usage.", "schema": { "type": "integer", "format": "int32" } }, { "name": "end_at", "in": "query", "required": true, "description": "The end time to export the gateway instance core usage.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Successfully exported the data plane core usage history as CSV.", "content": { "text/csv": { "schema": { "type": "string", "description": "CSV text with `time` and `max_dp_cores` columns." }, "example": "time,max_dp_cores\n1749132000,9\n1749128400,9\n1749124800,9\n1749121200,9\n1749117600,9\n1749114000,9\n1749110400,9\n1749106800,17\n1749103200,1\n1749099600,1\n1749096000,1\n1749092400,1\n1749088800,1\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/debug_sessions": { "post": { "tags": [ "Debugger" ], "summary": "Create a debug session", "operationId": "createDebugSession", "description": "IAM Action: `gateway:CreateDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "target_instances" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "target_instances": { "type": "array", "minItems": 1, "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true }, "max_samples": { "type": "integer", "description": "Maximum number of traces returned by the list API.", "minimum": 1, "maximum": 200, "default": 5 }, "duration_secs": { "type": "integer", "description": "Time-to-live in seconds for data plane configuration.", "minimum": 10, "maximum": 600, "default": 60 } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the debug session.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "target_instances": { "type": "array", "minItems": 1, "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true }, "max_samples": { "type": "integer", "description": "Maximum number of traces returned by the list API." }, "duration_secs": { "type": "integer", "description": "Time-to-live in seconds for data plane configuration." }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "started_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "stopped_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "completed_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Debugger" ], "summary": "List debug sessions", "operationId": "listDebugSessions", "description": "IAM Action: `gateway:GetDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of debug sessions.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of debug sessions.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "target_instances": { "type": "array", "minItems": 1, "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true }, "max_samples": { "type": "integer", "description": "Maximum number of traces returned by the list API." }, "duration_secs": { "type": "integer", "description": "Time-to-live in seconds for data plane configuration." }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "started_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "stopped_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "completed_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/debug_sessions/{debug_session_id}": { "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "debug_session_id", "in": "path", "required": true, "description": "Debug session ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "get": { "tags": [ "Debugger" ], "summary": "Get a debug session", "operationId": "getDebugSession", "description": "IAM Action: `gateway:GetDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "responses": { "200": { "description": "Successfully retrieved or modified the debug session.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "target_instances": { "type": "array", "minItems": 1, "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true }, "max_samples": { "type": "integer", "description": "Maximum number of traces returned by the list API." }, "duration_secs": { "type": "integer", "description": "Time-to-live in seconds for data plane configuration." }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "started_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "stopped_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "completed_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Debugger" ], "summary": "Delete a debug session", "operationId": "deleteDebugSession", "description": "IAM Action: `gateway:DeleteDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/debug_sessions/{debug_session_id}/stop": { "post": { "tags": [ "Debugger" ], "summary": "Stop a debug session", "operationId": "stopDebugSession", "description": "IAM Action: `gateway:StopDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "debug_session_id", "in": "path", "required": true, "description": "Debug session ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved or modified the debug session.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "target_instances": { "type": "array", "minItems": 1, "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true }, "max_samples": { "type": "integer", "description": "Maximum number of traces returned by the list API." }, "duration_secs": { "type": "integer", "description": "Time-to-live in seconds for data plane configuration." }, "status": { "type": "string", "enum": [ "active", "completed", "cancelled" ] }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "started_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "stopped_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "completed_at": { "nullable": true, "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/debug_sessions/{debug_session_id}/traces": { "get": { "tags": [ "Debugger" ], "summary": "List traces of a debug session", "operationId": "listDebugSessionTraces", "description": "IAM Action: `GetDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "debug_session_id", "in": "path", "required": true, "description": "Debug session ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of debug traces.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of debug traces.", "items": { "type": "object", "properties": { "trace_id": { "type": "string", "description": "Trace ID." }, "service_name": { "type": "string" }, "instance_id": { "type": "string" }, "root_span_name": { "type": "string" }, "http_method": { "type": "string" }, "http_url": { "type": "string" }, "http_status_code": { "type": "integer" }, "duration_ms": { "type": "number", "format": "double" }, "start_time": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/debug_sessions/{debug_session_id}/traces/{trace_id}": { "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "debug_session_id", "in": "path", "required": true, "description": "Debug session ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "trace_id", "in": "path", "required": true, "description": "Trace ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "get": { "tags": [ "Debugger" ], "summary": "Get a trace detail", "operationId": "getDebugSessionTrace", "description": "IAM Action: `GetDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "responses": { "200": { "description": "Successfully retrieved the debug trace details in OTLP format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceSpans": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "object", "description": "OTLP AnyValue, represented as a oneof-style object.", "properties": { "stringValue": { "type": "string" }, "boolValue": { "type": "boolean" }, "intValue": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "doubleValue": { "type": "number" }, "bytesValue": { "type": "string" }, "arrayValue": { "type": "object" }, "kvlistValue": { "type": "object" } } } } } } } }, "scopeSpans": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "spans": { "type": "array", "items": { "type": "object", "properties": { "traceId": { "type": "string" }, "spanId": { "type": "string" }, "parentSpanId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "integer" }, "startTimeUnixNano": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "endTimeUnixNano": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "object", "description": "OTLP AnyValue, represented as a oneof-style object.", "properties": { "stringValue": { "type": "string" }, "boolValue": { "type": "boolean" }, "intValue": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "doubleValue": { "type": "number" }, "bytesValue": { "type": "string" }, "arrayValue": { "type": "object" }, "kvlistValue": { "type": "object" } } } } } }, "status": { "type": "object" } } } } } } } } } } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/debug_sessions/{debug_session_id}/traces/{trace_id}/download": { "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "debug_session_id", "in": "path", "required": true, "description": "Debug session ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "trace_id", "in": "path", "required": true, "description": "Trace ID.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "post": { "tags": [ "Debugger" ], "summary": "Download a trace", "operationId": "downloadDebugSessionTrace", "description": "IAM Action: `gateway:ExportDebugSession`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "responses": { "200": { "description": "Successfully downloaded the debug trace data in OTLP format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceSpans": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "object", "description": "OTLP AnyValue, represented as a oneof-style object.", "properties": { "stringValue": { "type": "string" }, "boolValue": { "type": "boolean" }, "intValue": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "doubleValue": { "type": "number" }, "bytesValue": { "type": "string" }, "arrayValue": { "type": "object" }, "kvlistValue": { "type": "object" } } } } } } } }, "scopeSpans": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } } }, "spans": { "type": "array", "items": { "type": "object", "properties": { "traceId": { "type": "string" }, "spanId": { "type": "string" }, "parentSpanId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "integer" }, "startTimeUnixNano": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "endTimeUnixNano": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "object", "description": "OTLP AnyValue, represented as a oneof-style object.", "properties": { "stringValue": { "type": "string" }, "boolValue": { "type": "boolean" }, "intValue": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "doubleValue": { "type": "number" }, "bytesValue": { "type": "string" }, "arrayValue": { "type": "object" }, "kvlistValue": { "type": "object" } } } } } }, "status": { "type": "object" } } } } } } } } } } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/users": { "get": { "tags": [ "User" ], "summary": "List all users", "operationId": "listUsers", "description": "List dashboard user accounts with pagination and role-based filtering. Use this to audit who can authenticate by local credentials or configured SSO methods.\n**Required IAM Permission:** Action `iam:GetUser`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "roles", "in": "query", "schema": { "type": "array", "description": "Any array of roles.", "items": { "type": "string" }, "minimum": 1 } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of users.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of users.", "items": { "description": "The details for a user. It's user-specific information in an organization.", "allOf": [ { "type": "object", "properties": { "id": { "description": "Operator ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "username": { "type": "string", "description": "Operator username.", "example": "admin" }, "name": { "type": "string", "description": "Operator name.", "example": "admin" }, "email": { "type": "string", "description": "Operator email.", "example": "test@email.com" }, "email_verified": { "type": "boolean", "description": "If true, the operator email is verified." } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "provider": { "type": "string", "description": "Method used for user authentication or provisioning source.", "enum": [ "builtin", "sso", "scim" ] }, "two_factor_enabled": { "type": "boolean", "description": "If true, the user has enabled two-factor authentication (TOTP)." }, "roles": { "description": "An array of roles to be assigned to a user.", "type": "array", "minItems": 1, "maxItems": 32, "items": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The unique identifier of the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "super_admin" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of the role.", "enum": [ "built_in", "custom" ] }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } } } } }, "boundaries": { "description": "An array of boundaries to be assigned to the user.", "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/users/{user_id}": { "get": { "tags": [ "User" ], "summary": "Get a user", "operationId": "getUser", "description": "Get one dashboard user account by ID to inspect account details and current state.\n**Required IAM Permission:** Action `iam:GetUser`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "user_id", "in": "path", "description": "The user ID.", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the user.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The details for a user. It's user-specific information in an organization.", "allOf": [ { "type": "object", "properties": { "id": { "description": "Operator ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "username": { "type": "string", "description": "Operator username.", "example": "admin" }, "name": { "type": "string", "description": "Operator name.", "example": "admin" }, "email": { "type": "string", "description": "Operator email.", "example": "test@email.com" }, "email_verified": { "type": "boolean", "description": "If true, the operator email is verified." } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "provider": { "type": "string", "description": "Method used for user authentication or provisioning source.", "enum": [ "builtin", "sso", "scim" ] }, "two_factor_enabled": { "type": "boolean", "description": "If true, the user has enabled two-factor authentication (TOTP)." }, "roles": { "description": "An array of roles to be assigned to a user.", "type": "array", "minItems": 1, "maxItems": 32, "items": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The unique identifier of the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "super_admin" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of the role.", "enum": [ "built_in", "custom" ] }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } } } } }, "boundaries": { "description": "An array of boundaries to be assigned to the user.", "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "User" ], "summary": "Update basic attributes of a user", "operationId": "updateUser", "description": "Update basic attributes of a specified dashboard user account. This is intended for administrative account maintenance.\n**Required IAM Permission:** Action `iam:UpdateUser`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "user_id", "in": "path", "description": "The user ID.", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } }, "required": true }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "delete": { "tags": [ "User" ], "summary": "Delete a user", "operationId": "deleteUser", "description": "Delete a dashboard user account and revoke its login access. Verify downstream ownership and role dependencies before removal.\n**Required IAM Permission:** Action `iam:DeleteUser`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "user_id", "in": "path", "description": "The user ID.", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/users/{user_id}/boundaries": { "put": { "tags": [ "User" ], "summary": "Update the user's permission boundaries", "operationId": "updateUserBoundaries", "description": "Replace a user's permission boundaries using permission policy IDs. Boundaries constrain the maximum effective permissions a user can obtain.\n**Required IAM Permission:** Action `iam:UpdateUserBoundary`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "user_id", "in": "path", "description": "The user ID.", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "An array of permission policy ID.", "items": { "type": "string", "example": "efd3bcc7-b61a-47ec-942b-b36bf249f1da" } } } } }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/users/{user_id}/password_reset": { "put": { "tags": [ "User" ], "summary": "Reset the password to specific value", "operationId": "passwordReset", "description": "Reset a specified user's password to an administrator-provided value. Use this for recovery or emergency credential rotation.\n**Required IAM Permission:** Action `iam:ResetPassword`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "user_id", "in": "path", "description": "The user ID.", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The request to reset the password.", "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "description": "The password of the user.", "minLength": 1, "maxLength": 128, "example": "safe-password" } } } } }, "required": true }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/users/{user_id}/2fa_reset": { "put": { "tags": [ "User" ], "summary": "Reset (disable) a user's two-factor authentication", "operationId": "resetTwoFactor", "description": "Administratively disable a specified user's two-factor authentication, for example when the user has lost their authenticator device.\n**Required IAM Permission:** Action `iam:ResetTwoFactor`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "user_id", "in": "path", "description": "The user ID.", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/me": { "get": { "tags": [ "User" ], "summary": "Get my user detail", "operationId": "getUserMe", "description": "Get details of the currently authenticated dashboard user.", "responses": { "200": { "description": "Successfully retrieved the user.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The details for a user. It's user-specific information in an organization.", "allOf": [ { "type": "object", "properties": { "id": { "description": "Operator ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "username": { "type": "string", "description": "Operator username.", "example": "admin" }, "name": { "type": "string", "description": "Operator name.", "example": "admin" }, "email": { "type": "string", "description": "Operator email.", "example": "test@email.com" }, "email_verified": { "type": "boolean", "description": "If true, the operator email is verified." } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "provider": { "type": "string", "description": "Method used for user authentication or provisioning source.", "enum": [ "builtin", "sso", "scim" ] }, "two_factor_enabled": { "type": "boolean", "description": "If true, the user has enabled two-factor authentication (TOTP)." }, "roles": { "description": "An array of roles to be assigned to a user.", "type": "array", "minItems": 1, "maxItems": 32, "items": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The unique identifier of the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "super_admin" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of the role.", "enum": [ "built_in", "custom" ] }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } } } } }, "boundaries": { "description": "An array of boundaries to be assigned to the user.", "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "User" ], "summary": "Update my user profile", "operationId": "putUserMe", "description": "Update profile attributes of the currently authenticated dashboard user without changing role assignments.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } } } } }, "required": true }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/me/email": { "put": { "tags": [ "User" ], "summary": "Update the user email", "operationId": "putUserEmail", "description": "Update the email address for the currently authenticated user account.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 128 } } } } }, "required": true }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "delete": { "tags": [ "User" ], "summary": "Delete the user email", "operationId": "deleteUserEmail", "description": "Remove the email address currently bound to the authenticated user account.", "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/me/2fa/setup": { "post": { "tags": [ "User" ], "summary": "Start two-factor (2FA) enrollment for the current user", "operationId": "setupTwoFactor", "description": "Generate a new TOTP secret for the currently authenticated user and return it together with a provisioning URI and QR code. The secret is not active until confirmed via the enable endpoint.", "responses": { "200": { "description": "Two-factor enrollment started. Returns the secret and a QR code to register in an authenticator app.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "secret": { "type": "string", "description": "The base32 shared secret for manual entry into an authenticator app." }, "otpauth_url": { "type": "string", "description": "The otpauth:// provisioning URI." }, "qr_code": { "type": "string", "description": "A data URI (data:image/png;base64,...) QR code encoding the provisioning URI." } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/me/2fa/enable": { "post": { "tags": [ "User" ], "summary": "Confirm and enable two-factor (2FA) for the current user", "operationId": "enableTwoFactor", "description": "Confirm a pending TOTP secret with a valid code and enable two-factor authentication. Returns one-time recovery codes that are shown only once.", "requestBody": { "content": { "application/json": { "schema": { "description": "A two-factor verification code (TOTP or one-time recovery code).", "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The TOTP code or a one-time recovery code.", "minLength": 1, "maxLength": 64 } } } } }, "required": true }, "responses": { "200": { "description": "Two-factor authentication enabled. Returns one-time recovery codes shown only once.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "recovery_codes": { "type": "array", "description": "One-time recovery codes. Store them securely; each can be used once if the authenticator device is unavailable.", "items": { "type": "string" } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/me/2fa/disable": { "post": { "tags": [ "User" ], "summary": "Disable two-factor (2FA) for the current user", "operationId": "disableTwoFactor", "description": "Disable two-factor authentication for the currently authenticated user after validating a current TOTP or recovery code.", "requestBody": { "content": { "application/json": { "schema": { "description": "A two-factor verification code (TOTP or one-time recovery code).", "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The TOTP code or a one-time recovery code.", "minLength": 1, "maxLength": 64 } } } } }, "required": true }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/email_verified": { "get": { "tags": [ "Email" ], "summary": "Check if an email is verified", "operationId": "checkEmailVerified", "description": "Check whether the specified email address has completed verification. Use this to gate workflows that require verified contact information.", "parameters": [ { "name": "email", "in": "query", "required": true, "description": "Email address.", "schema": { "type": "string", "format": "email", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Successfully retrieved the email verification status.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "verified": { "type": "boolean" } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/verify_email": { "get": { "tags": [ "Email" ], "summary": "Get email verification", "operationId": "getEmailVerification", "description": "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.", "parameters": [ { "name": "token", "description": "The token of the request.", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 1024 } } ], "responses": { "302": { "description": "Redirect to IdP.", "content": {} }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/invites": { "post": { "tags": [ "User" ], "summary": "Invite a user", "operationId": "inviteUser", "description": "Invite a new dashboard user account. The invitation initiates onboarding so the user can later sign in with supported authentication methods.\n**Required IAM Permission:** Action `iam:InviteUser`, Resource `arn:api7:iam:user/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "description": "The username of the user.", "type": "string", "minLength": 1, "maxLength": 128 }, "password": { "type": "string", "description": "The password of the user.", "minLength": 1, "maxLength": 128, "example": "safe-password" }, "boundaries": { "description": "The permission boundaries of the user.", "type": "array", "items": { "type": "string" } }, "name": { "description": "The name of the user.", "type": "string", "minLength": 1, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "User invitation created successfully. Returns the user with an invitation link.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The details for a user. It's user-specific information in an organization.", "allOf": [ { "type": "object", "properties": { "id": { "description": "Operator ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "username": { "type": "string", "description": "Operator username.", "example": "admin" }, "name": { "type": "string", "description": "Operator name.", "example": "admin" }, "email": { "type": "string", "description": "Operator email.", "example": "test@email.com" }, "email_verified": { "type": "boolean", "description": "If true, the operator email is verified." } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "provider": { "type": "string", "description": "Method used for user authentication or provisioning source.", "enum": [ "builtin", "sso", "scim" ] }, "two_factor_enabled": { "type": "boolean", "description": "If true, the user has enabled two-factor authentication (TOTP)." }, "roles": { "description": "An array of roles to be assigned to a user.", "type": "array", "minItems": 1, "maxItems": 32, "items": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The unique identifier of the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "super_admin" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of the role.", "enum": [ "built_in", "custom" ] }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } } } } }, "boundaries": { "description": "An array of boundaries to be assigned to the user.", "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] }, { "type": "object", "properties": { "invitation_link": { "type": "string", "description": "The invitation link of the user." } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/password": { "put": { "tags": [ "User" ], "summary": "Update my user password", "operationId": "updateUserPassword", "description": "Change the password for the currently authenticated user account.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "new_password" ], "properties": { "old_password": { "type": "string", "minLength": 1, "maxLength": 128, "example": "old-password" }, "new_password": { "type": "string", "minLength": 1, "maxLength": 128, "example": "new-password" } } } } }, "required": true }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/login": { "post": { "tags": [ "User" ], "summary": "Log in to API7 Enterprise using the built-in username and password", "operationId": "userLogin", "description": "Authenticate a dashboard user with built-in username and password credentials and create a session.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "description": "The username of the user.", "type": "string", "minLength": 1, "maxLength": 128, "example": "john" }, "password": { "type": "string", "description": "The password of the user.", "minLength": 1, "maxLength": 128, "example": "safe-password" }, "otp": { "description": "The two-factor authentication code. Required only when the account has 2FA enabled. Accepts a TOTP code from an authenticator app or a one-time recovery code.", "type": "string", "minLength": 1, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/logout": { "post": { "tags": [ "User" ], "summary": "Log out from API7 Enterprise using the built-in username and password", "operationId": "userLogout", "description": "Log out the current built-in authentication session and invalidate related session state.", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } } } } }, "/api/users/{user_id}/assigned_roles": { "put": { "tags": [ "User", "Role" ], "summary": "Update assigned roles for a user", "operationId": "addAssignedRole", "description": "Update role assignments for a user. Assigned roles determine the permission policies and effective access granted to that account.\n**Required IAM Permission:** Action `iam:UpdateUserRole`, Resource `arn:api7:iam:user/%s`", "parameters": [ { "name": "user_id", "in": "path", "description": "The user ID.", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "An array of role IDs associated with a user.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } }, "required": [ "roles" ] } } }, "required": true }, "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/roles": { "get": { "tags": [ "Role" ], "summary": "List all roles", "operationId": "listRoles", "description": "List RBAC roles with pagination and filtering. Results include built-in roles (Super Admin, Admin, Viewer) and custom roles.\n**Required IAM Permission:** Action `iam:GetRole`, Resource `arn:api7:iam:role/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of roles.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of roles.", "items": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "View Consumer" }, "desc": { "example": "This role allows users to view comsumers.", "description": "The object description.", "type": "string", "maxLength": 65536 }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "enum": [ "built_in", "custom" ], "description": "Type of the role.", "example": "custom" }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "post": { "tags": [ "Role" ], "summary": "Create a role", "operationId": "createRole", "description": "Create a custom RBAC role used to group permission policies. The new role can then be assigned to users.\n**Required IAM Permission:** Action `iam:CreateRole`, Resource `arn:api7:iam:role/*`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The role name.", "example": "View Consumer", "minLength": 1, "maxLength": 256 }, "desc": { "example": "This role allows users to view comsumers.", "description": "The object description.", "type": "string", "maxLength": 65536 }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "policies": { "type": "array", "description": "The polices attached to the role.", "minItems": 1, "uniqueItems": true, "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } } } }, "responses": { "200": { "description": "Successfully retrieved the role.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "View Consumer" }, "desc": { "example": "This role allows users to view comsumers.", "description": "The object description.", "type": "string", "maxLength": 65536 }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "enum": [ "built_in", "custom" ], "description": "Type of the role.", "example": "custom" }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/roles/{role_id}": { "get": { "tags": [ "Role" ], "summary": "Get a role", "operationId": "getRole", "description": "Get detailed information for a specific RBAC role. This includes role metadata used to grant permissions through user-role assignments.\n**Required IAM Permission:** Action `iam:GetRole`, Resource `arn:api7:iam:role/%s`", "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "Role ID.", "example": "4b9b56d1-147e-49ef-bcaa-88cc5bcf403f", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the role.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "View Consumer" }, "desc": { "example": "This role allows users to view comsumers.", "description": "The object description.", "type": "string", "maxLength": 65536 }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "enum": [ "built_in", "custom" ], "description": "Type of the role.", "example": "custom" }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "Role" ], "summary": "Update a role", "operationId": "putRole", "description": "Update a role definition by ID. Changes affect all users currently assigned to the role.\n**Required IAM Permission:** Action `iam:UpdateRole`, Resource `arn:api7:iam:role/%s`", "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "Role ID.", "example": "4b9b56d1-147e-49ef-bcaa-88cc5bcf403f", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The role name.", "example": "View Consumer", "minLength": 1, "maxLength": 256 }, "desc": { "example": "This role allows users to view comsumers.", "description": "The object description.", "type": "string", "maxLength": 65536 }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "policies": { "type": "array", "description": "The polices attached to the role.", "minItems": 1, "uniqueItems": true, "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } } } }, "responses": { "200": { "description": "Successfully retrieved the role.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The specification of the role of the user.", "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The role name.", "example": "View Consumer" }, "desc": { "example": "This role allows users to view comsumers.", "description": "The object description.", "type": "string", "maxLength": 65536 }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "enum": [ "built_in", "custom" ], "description": "Type of the role.", "example": "custom" }, "policies": { "type": "array", "description": "The policies of the role.", "items": { "type": "string", "example": "super-admin-permission-policy" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Role" ], "summary": "Delete a role", "operationId": "deleteRole", "description": "Delete a custom RBAC role from the organization. Review user assignments first to avoid unintended access loss.\n**Required IAM Permission:** Action `iam:DeleteRole`, Resource `arn:api7:iam:role/%s`", "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "Role ID.", "example": "4b9b56d1-147e-49ef-bcaa-88cc5bcf403f", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/roles/{role_id}/permission_policies": { "get": { "tags": [ "Role", "Permission Policy" ], "summary": "List all permission policies attached to a role", "operationId": "listRolePermissionPolicies", "description": "List permission policies attached to a role. This reveals the policy statements that determine the role's effective access.\n**Required IAM Permission:** Action `iam:GetPermissionPolicy`, Resource `arn:api7:iam:permissionpolicy/%s`", "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "Role ID.", "example": "4b9b56d1-147e-49ef-bcaa-88cc5bcf403f", "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of permission policies.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of permission policies.", "items": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/roles/{role_id}/attach_permission_policies": { "post": { "tags": [ "Role", "Permission Policy" ], "summary": "Attach permission policies to a role", "operationId": "attachPermissionPolicies", "description": "Attach permission policies to a role. Attached policies immediately affect all users assigned to that role.\n**Required IAM Permission:** Action `iam:UpdateRole`, Resource `arn:api7:iam:role/%s`", "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "Role ID.", "example": "4b9b56d1-147e-49ef-bcaa-88cc5bcf403f", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "An array of permission policy ID.", "items": { "type": "string", "example": "efd3bcc7-b61a-47ec-942b-b36bf249f1da" } } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/roles/{role_id}/detach_permission_policies": { "post": { "tags": [ "Role", "Permission Policy" ], "summary": "Detach permission policies of a role", "operationId": "detachPermissionPolicies", "description": "Detach permission policies from a role. Removing policies may reduce or revoke access for assigned users.\n**Required IAM Permission:** Action `iam:UpdateRole`, Resource `arn:api7:iam:role/%s`", "parameters": [ { "name": "role_id", "in": "path", "required": true, "description": "Role ID.", "example": "4b9b56d1-147e-49ef-bcaa-88cc5bcf403f", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "An array of permission policy ID.", "items": { "type": "string", "example": "efd3bcc7-b61a-47ec-942b-b36bf249f1da" } } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/permission_policies": { "post": { "tags": [ "Permission Policy" ], "summary": "Create a permission policy", "operationId": "createPermissionPolicy", "description": "Create a fine-grained permission policy with allow/deny statements over specific IAM actions and resource ARNs.\n**Required IAM Permission:** Action `iam:CreatePermissionPolicy`, Resource `arn:api7:iam:permissionpolicy/*`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] } } } }, "responses": { "200": { "description": "Successfully retrieved the permission policy.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Permission Policy" ], "summary": "List all permission policies", "operationId": "listPermissionPolicies", "description": "List available permission policies in the organization with pagination and filters. Use this to choose policies for roles and boundaries.\n**Required IAM Permission:** Action `iam:GetPermissionPolicy`, Resource `arn:api7:iam:permissionpolicy/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of permission policies.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of permission policies.", "items": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/permission_policies/{permission_policy_id}": { "get": { "tags": [ "Permission Policy" ], "summary": "Get a permission policy", "operationId": "getPermissionPolicy", "description": "Get a permission policy by ID, including all statements and metadata.\n**Required IAM Permission:** Action `iam:GetPermissionPolicy`, Resource `arn:api7:iam:permissionpolicy/%s`", "parameters": [ { "name": "permission_policy_id", "in": "path", "required": true, "description": "Permission policy ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the permission policy.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "Permission Policy" ], "summary": "Update a permission policy", "operationId": "putPermissionPolicy", "description": "Update an existing permission policy definition. Changes apply to all roles or users that reference this policy.\n**Required IAM Permission:** Action `iam:UpdatePermissionPolicy`, Resource `arn:api7:iam:permissionpolicy/%s`", "parameters": [ { "name": "permission_policy_id", "in": "path", "required": true, "description": "Permission policy ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] } } } }, "responses": { "200": { "description": "Successfully retrieved the permission policy.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "name": { "description": "The policy name.", "example": "sample-policy", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "The permission policy type.", "enum": [ "built_in", "custom" ] }, "desc": { "description": "The description of the policy.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "description": "The labels of the policy.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "policy_document": { "type": "object", "description": "Policy document.", "properties": { "statement": { "type": "array", "description": "The statements of the policy.", "minItems": 1, "items": { "type": "object", "properties": { "effect": { "type": "string", "description": "The effect of the statement.", "enum": [ "allow", "deny" ] }, "resources": { "type": "array", "description": "The resources for requests.", "items": { "type": "string", "example": "gateway:GatewayGroup" }, "minItems": 1, "example": [ "arn:api7:gateway:servicetemplate/<.*>" ] }, "actions": { "type": "array", "description": "The actions for requests.", "items": { "anyOf": [ { "type": "string" } ] }, "example": [ "gateway:GetServiceTemplate" ], "minItems": 1 }, "conditions": { "type": "object", "description": "Rules for matching requests. The key is the condition name, the value is the condition expression \nwhich specifies the function name and parameter structure of condition.\n", "anyOf": [ { "title": "Condition for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } }, "example": { "gateway_group_label": { "type": "MatchLabel", "options": { "key": "env", "operator": "exact_match", "value": "prod" } } } }, { "title": "Condition for Service", "type": "object", "properties": { "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Condition for permission policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "service_label": { "description": "Condition for service label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Role", "type": "object", "properties": { "role_label": { "description": "Condition for role label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for User", "type": "object", "properties": { "user_label": { "description": "Condition for user label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "permission_boundaries": { "description": "Condition for permission boundaries.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "AllOfStrings", "enum": [ "AllOfStrings" ] }, "options": { "type": "array", "description": "An array of options.", "items": { "type": "string" } } }, "example": { "type": "AllOfStrings", "options": [ "permission_policy_a", "permission_policy_b" ] } } } }, { "title": "Condition for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "consumer_label": { "description": "Condition for consumer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Condition for gateway group label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } }, "secret_provider_label": { "description": "Condition for secret provider label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Condition for contact point label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Condition for alert policy label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Developer", "type": "object", "properties": { "developer_label": { "description": "Condition for developer label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for API Product", "type": "object", "properties": { "api_product_label": { "description": "Condition for API product label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "Condition for CA certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Condition for certificate label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for SNI", "type": "object", "properties": { "sni_label": { "description": "Condition for SNI label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } }, { "title": "Condition for Portal", "type": "object", "properties": { "portal_label": { "description": "Condition for portal label.", "type": "object", "properties": { "type": { "type": "string", "description": "Type of condition.", "example": "MatchLabel", "enum": [ "MatchLabel" ] }, "options": { "type": "object", "description": "Matching expressions.", "properties": { "key": { "type": "string", "description": "The label key to match against." }, "operator": { "type": "string", "description": "The comparison operator used for matching the label.", "enum": [ "exact_match", "contains_string", "present" ] }, "value": { "type": "string", "description": "The value to compare against the label." } } } } } } } ] } }, "required": [ "effect", "resources", "actions" ], "additionalProperties": false } } }, "required": [ "statement" ], "additionalProperties": false } }, "required": [ "name", "policy_document" ] }, { "type": "object", "properties": { "id": { "description": "The policy ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Permission Policy" ], "summary": "Delete a permission policy", "operationId": "deletePermissionPolicy", "description": "Delete a permission policy. Ensure references are reviewed first to prevent accidental permission breakage.\n**Required IAM Permission:** Action `iam:DeletePermissionPolicy`, Resource `arn:api7:iam:permissionpolicy/%s`", "parameters": [ { "name": "permission_policy_id", "in": "path", "required": true, "description": "Permission policy ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/permission_policies/{permission_policy_id}/references": { "get": { "tags": [ "Permission Policy" ], "summary": "List the Roles or Users that directly reference the Permission Policy", "operationId": "listPermissionPolicyReferences", "description": "List roles and users that directly reference the specified permission policy. This helps estimate impact before policy changes.\n**Required IAM Permission:** Action `iam:GetPermissionPolicy`, Resource `arn:api7:iam:permissionpolicy/%s`", "parameters": [ { "name": "permission_policy_id", "in": "path", "required": true, "description": "Permission policy ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of resources referencing the permission policy.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "description": "Indicates which Role or User references the PermissionPolicy.", "properties": { "type": { "type": "string", "description": "Referenced by Role or User.", "enum": [ "role", "user" ] }, "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "example": "consumer role", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/allow_access": { "post": { "tags": [ "Role", "User" ], "summary": "Check if a user has permissions on specific resources", "operationId": "checkAllowAccess", "description": "Evaluate whether a user is allowed to perform specified actions on given resources based on current RBAC and policy configuration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "title": "properties", "type": "object", "properties": { "resource": { "type": "string", "description": "An ARN-style identifier that specifies one or multiple resources." }, "action": { "type": "string", "description": "A specific permission that defines what operation can be performed on the resource." }, "context": { "type": "object", "description": "Additional conditions or labels used to further narrow down which resources the action applies to, in combination with the resource definition.", "anyOf": [ { "title": "Context for Gateway Group", "type": "object", "properties": { "gateway_group_label": { "description": "Gateway group label.", "type": "object", "additionalProperties": { "type": "string" } } }, "example": { "gateway_group_label": { "env": "prod" } } }, { "title": "Context for Service", "type": "object", "properties": { "service_label": { "description": "Service label.", "type": "object", "additionalProperties": { "type": "string" } } }, "example": { "service_label": { "version": "v1" } } }, { "title": "Context for Published Service", "type": "object", "properties": { "gateway_group_label": { "description": "Gateway group label.", "type": "object", "additionalProperties": { "type": "string" } }, "service_label": { "description": "Service label.", "type": "object", "additionalProperties": { "type": "string" } } }, "example": { "gateway_group_label": { "env": "prod" }, "service_label": { "version": "v2" } } }, { "title": "Context for Role", "type": "object", "properties": { "role_label": { "description": "Role label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for Permission Policy", "type": "object", "properties": { "permission_policy_label": { "description": "Permission policy label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for User", "type": "object", "properties": { "user_label": { "description": "User label.", "type": "object", "additionalProperties": { "type": "string" } }, "permission_boundaries": { "description": "A list of permission boundaries.", "type": "array", "items": { "type": "string" } } } }, { "title": "Context for Consumer", "type": "object", "properties": { "gateway_group_label": { "description": "Gateway group label.", "type": "object", "additionalProperties": { "type": "string" } }, "consumer_label": { "description": "Consumer label.", "type": "object", "additionalProperties": { "type": "string" } } }, "example": { "gateway_group_label": { "env": "prod" }, "consumer_label": { "team": "frontend" } } }, { "title": "Context for Secret", "type": "object", "properties": { "gateway_group_label": { "description": "Gateway group label.", "type": "object", "additionalProperties": { "type": "string" } }, "secret_provider_label": { "description": "Secret provider label.", "type": "object", "additionalProperties": { "type": "string" } } }, "example": { "gateway_group_label": { "env": "prod" }, "secret_provider_label": { "provider": "aws" } } }, { "title": "Context for Contact Point", "type": "object", "properties": { "contact_point_label": { "description": "Contact point label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for Alert Policy", "type": "object", "properties": { "alert_policy_label": { "description": "Alert policy label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for Developer", "type": "object", "properties": { "developer_label": { "description": "Developer label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for API Product", "type": "object", "properties": { "api_product_label": { "description": "API product label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for CA Certificate", "type": "object", "properties": { "ca_certificate_label": { "description": "CA certificate label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for Certificate", "type": "object", "properties": { "certificate_label": { "description": "Certificate label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for SNI", "type": "object", "properties": { "sni_label": { "description": "SNI label.", "type": "object", "additionalProperties": { "type": "string" } } } }, { "title": "Context for Portal", "type": "object", "properties": { "portal_label": { "description": "Portal label.", "type": "object", "additionalProperties": { "type": "string" } } } } ] } }, "required": [ "resource", "action" ] }, "example": { "hasAccess": { "resource": "arn:api7:iam:role/767ff422-614b-4c0c-a4ea-287c26c773ba", "action": "iam:UpdateCustomRole", "context": { "role_label": { "platform": "external" } } } } } } } }, "responses": { "200": { "description": "Successfully checked whether the user has the specified access permissions.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": { "type": "boolean" } } } } ] }, "example": { "value": { "hasAccess": true } } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/control_plane/prometheus/{prometheus_path}": { "get": { "tags": [ "Monitoring" ], "summary": "Get data from Prometheus", "operationId": "getPrometheusData", "parameters": [ { "name": "prometheus_path", "in": "path", "required": true, "description": "Prometheus HTTP API endpoint. See the [Prometheus docs](https://prometheus.io/docs/prometheus/latest/querying/api/) for the available URL query parameters for each endpoint.", "schema": { "type": "string", "anyOf": [ { "title": "Fixed Endpoints", "enum": [ "api/v1/query", "api/v1/query_range", "api/v1/format_query", "api/v1/series", "api/v1/labels" ] }, { "title": "Dynamic Label Values Endpoint", "pattern": "^api/v1/label/[^/]+/values$" } ] } } ], "responses": { "200": { "description": "The Prometheus proxy response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "The Prometheus raw data.", "additionalProperties": true, "example": { "status": "success", "data": { "resultType": "matrix", "result": [ { "metric": { "label": "xxx" }, "values": [ [ 1684740675, 1 ], [ 1684740690, 2 ] ] } ] } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "post": { "tags": [ "Monitoring" ], "summary": "Get data from Prometheus", "operationId": "getPrometheusDataWithPost", "parameters": [ { "name": "prometheus_path", "in": "path", "required": true, "description": "Prometheus HTTP API endpoint. See the [Prometheus docs](https://prometheus.io/docs/prometheus/latest/querying/api/) for the available body parameters for each endpoint.", "schema": { "type": "string", "anyOf": [ { "title": "Fixed Endpoints", "enum": [ "api/v1/query", "api/v1/query_range", "api/v1/format_query", "api/v1/series", "api/v1/labels" ] }, { "title": "Dynamic Label Values Endpoint", "pattern": "^api/v1/label/[^/]+/values$" } ] } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "The Prometheus proxy response.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "The Prometheus raw data.", "additionalProperties": true, "example": { "status": "success", "data": { "resultType": "matrix", "result": [ { "metric": { "label": "xxx" }, "values": [ [ 1684740675, 1 ], [ 1684740690, 2 ] ] } ] } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/alert/policies": { "get": { "tags": [ "Alert" ], "summary": "List all alert policies", "operationId": "listAlertPolicies", "description": "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.\n\n**Required IAM Permission:** Action `gateway:GetAlertPolicy`, Resource `arn:api7:gateway:alert/%s`", "parameters": [ { "name": "order_by", "in": "query", "description": "Index to order alert policies by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "name", "severity" ] } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "status", "in": "query", "required": false, "description": "Alert enablement status.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "enabled", "disabled" ] } } }, { "name": "severity", "in": "query", "required": false, "description": "Alert severity.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "high", "medium", "low" ] } } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of alert policies.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The definition of an alert policy.", "items": { "type": "object", "properties": { "name": { "description": "The alert policy name.", "example": "500 status alert", "type": "string", "minLength": 1, "maxLength": 100 }, "desc": { "description": "The alert policy description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enable": { "type": "boolean", "description": "If true, enable the alert policy.", "default": true }, "check_interval": { "type": "integer", "description": "The check interval for the alert policy. The unit is second.", "minimum": 1, "maximum": 86400 }, "severity": { "type": "string", "description": "The alert severity level.", "default": "medium", "enum": [ "high", "medium", "low" ] }, "trigger_logical_operator": { "type": "string", "description": "The logical relationship between multiple triggers.", "enum": [ "All", "Any" ], "default": "All" }, "id": { "type": "string", "description": "The alert policy ID.", "minLength": 1, "example": "509fd356-df70-480b-8622-c38e27cfdd99" }, "created_at": { "description": "The create timestamp of an alert policy.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The update timestamp of an alert policy.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } } ] } } } } } }, "post": { "tags": [ "Alert" ], "summary": "Create an alert policy", "operationId": "createAlertPolicy", "description": "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.\n\n**Required IAM Permission:** Action `gateway:CreateAlertPolicy`, Resource `arn:api7:gateway:alert/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "trigger_logical_operator", "trigger_conditions" ], "properties": { "name": { "description": "The alert policy name.", "example": "500 status alert", "type": "string", "minLength": 1, "maxLength": 100 }, "desc": { "description": "The alert policy description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enable": { "type": "boolean", "description": "If true, enable the alert policy.", "default": true }, "check_interval": { "type": "integer", "description": "The check interval for the alert policy. The unit is second.", "minimum": 1, "maximum": 86400 }, "severity": { "type": "string", "description": "The alert severity level.", "default": "medium", "enum": [ "high", "medium", "low" ] }, "trigger_logical_operator": { "type": "string", "description": "The logical relationship between multiple triggers.", "enum": [ "All", "Any" ], "default": "All" }, "trigger_conditions": { "type": "array", "description": "The alert trigger conditions.", "minItems": 1, "items": { "type": "object", "oneOf": [ { "title": "Status Code", "properties": { "event": { "type": "string", "enum": [ "number_of_status_code", "ratio_of_status_code" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "service_id": { "description": "Published service ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "Published route ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "event_config": { "type": "object", "description": "Alert event configurations.", "properties": { "duration": { "type": "integer", "description": "The duration time.", "minimum": 1, "example": 60 }, "unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" }, "http_status_code": { "type": "string", "description": "The HTTP status code.", "pattern": "[2-5]\\d{2}|[2-5]xx", "example": "500" } }, "required": [ "http_status_code", "duration", "unit" ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "larger_equal", "larger_than" ], "example": "larger_than" }, "value": { "example": 5, "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "event_config", "operator", "value", "scope" ] }, { "title": "Certificate Expiry", "properties": { "event": { "type": "string", "enum": [ "ssl_certificate_will_expire_in", "gateway_certificate_will_expire_in" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "License Expiry", "properties": { "event": { "type": "string", "enum": [ "license_will_expire_in" ], "description": "The event of the trigger." }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit" ] }, { "title": "Gateway Instance Offline", "properties": { "event": { "type": "string", "enum": [ "gateway_instance_offline" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "equal", "larger_equal", "larger_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "Data Plane Cores Exceeded", "properties": { "event": { "type": "string", "enum": [ "dp_core_exceeded" ], "description": "The event of trigger." } } }, { "title": "Numbers of Healthy Gateway Instances", "properties": { "event": { "type": "string", "enum": [ "number_of_healthy_gateway_instances" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ], "default": "less_equal" }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Bytes", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_bytes" ], "description": "The event of trigger for shared dictionary free space monitoring in bytes." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The threshold in MB to trigger the alert.", "example": 100 } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Percentage", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_percentage" ], "description": "The event of trigger for shared dictionary free space monitoring in percentage." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] } ] } }, "notifications": { "type": "array", "description": "The alert notifications.", "items": { "type": "object", "required": [ "type" ], "oneOf": [ { "title": "Email", "type": "object", "required": [ "type", "subject", "content" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "email" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "subject": { "type": "string", "description": "The email subject.", "minLength": 1, "example": "API7 Notification" }, "content": { "type": "string", "description": "The email content.", "minLength": 1, "format": "go_template", "example": "The xxx gateway group has received more than 5 responses with 500 status code in the last 60 seconds." } } }, { "title": "Webhook", "type": "object", "required": [ "type", "alert_message" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "webhook" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "alert_message": { "type": "string", "description": "The alert message.", "minLength": 1, "format": "go_template" } } } ] } }, "debug_sessions": { "type": "array", "description": "Debug session configurations to create automatically when the alert is triggered.", "items": { "type": "object", "description": "Configuration for a debug session to be automatically created when the alert is triggered.", "required": [ "max_samples", "duration_secs" ], "properties": { "max_samples": { "type": "integer", "description": "The maximum number of trace samples to collect.", "minimum": 1, "maximum": 200, "example": 100 }, "duration_secs": { "type": "integer", "description": "The duration in seconds for the debug session.", "minimum": 10, "maximum": 600, "example": 300 }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true } } } } } } } }, "required": true }, "responses": { "200": { "description": "Alert policy created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The definition of an alert policy.", "type": "object", "allOf": [ { "type": "object", "required": [ "name", "trigger_logical_operator", "trigger_conditions" ], "properties": { "name": { "description": "The alert policy name.", "example": "500 status alert", "type": "string", "minLength": 1, "maxLength": 100 }, "desc": { "description": "The alert policy description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enable": { "type": "boolean", "description": "If true, enable the alert policy.", "default": true }, "check_interval": { "type": "integer", "description": "The check interval for the alert policy. The unit is second.", "minimum": 1, "maximum": 86400 }, "severity": { "type": "string", "description": "The alert severity level.", "default": "medium", "enum": [ "high", "medium", "low" ] }, "trigger_logical_operator": { "type": "string", "description": "The logical relationship between multiple triggers.", "enum": [ "All", "Any" ], "default": "All" }, "trigger_conditions": { "type": "array", "description": "The alert trigger conditions.", "minItems": 1, "items": { "type": "object", "oneOf": [ { "title": "Status Code", "properties": { "event": { "type": "string", "enum": [ "number_of_status_code", "ratio_of_status_code" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "service_id": { "description": "Published service ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "Published route ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "event_config": { "type": "object", "description": "Alert event configurations.", "properties": { "duration": { "type": "integer", "description": "The duration time.", "minimum": 1, "example": 60 }, "unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" }, "http_status_code": { "type": "string", "description": "The HTTP status code.", "pattern": "[2-5]\\d{2}|[2-5]xx", "example": "500" } }, "required": [ "http_status_code", "duration", "unit" ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "larger_equal", "larger_than" ], "example": "larger_than" }, "value": { "example": 5, "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "event_config", "operator", "value", "scope" ] }, { "title": "Certificate Expiry", "properties": { "event": { "type": "string", "enum": [ "ssl_certificate_will_expire_in", "gateway_certificate_will_expire_in" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "License Expiry", "properties": { "event": { "type": "string", "enum": [ "license_will_expire_in" ], "description": "The event of the trigger." }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit" ] }, { "title": "Gateway Instance Offline", "properties": { "event": { "type": "string", "enum": [ "gateway_instance_offline" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "equal", "larger_equal", "larger_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "Data Plane Cores Exceeded", "properties": { "event": { "type": "string", "enum": [ "dp_core_exceeded" ], "description": "The event of trigger." } } }, { "title": "Numbers of Healthy Gateway Instances", "properties": { "event": { "type": "string", "enum": [ "number_of_healthy_gateway_instances" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ], "default": "less_equal" }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Bytes", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_bytes" ], "description": "The event of trigger for shared dictionary free space monitoring in bytes." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The threshold in MB to trigger the alert.", "example": 100 } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Percentage", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_percentage" ], "description": "The event of trigger for shared dictionary free space monitoring in percentage." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] } ] } }, "notifications": { "type": "array", "description": "The alert notifications.", "items": { "type": "object", "required": [ "type" ], "oneOf": [ { "title": "Email", "type": "object", "required": [ "type", "subject", "content" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "email" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "subject": { "type": "string", "description": "The email subject.", "minLength": 1, "example": "API7 Notification" }, "content": { "type": "string", "description": "The email content.", "minLength": 1, "format": "go_template", "example": "The xxx gateway group has received more than 5 responses with 500 status code in the last 60 seconds." } } }, { "title": "Webhook", "type": "object", "required": [ "type", "alert_message" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "webhook" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "alert_message": { "type": "string", "description": "The alert message.", "minLength": 1, "format": "go_template" } } } ] } }, "debug_sessions": { "type": "array", "description": "Debug session configurations to create automatically when the alert is triggered.", "items": { "type": "object", "description": "Configuration for a debug session to be automatically created when the alert is triggered.", "required": [ "max_samples", "duration_secs" ], "properties": { "max_samples": { "type": "integer", "description": "The maximum number of trace samples to collect.", "minimum": 1, "maximum": 200, "example": 100 }, "duration_secs": { "type": "integer", "description": "The duration in seconds for the debug session.", "minimum": 10, "maximum": 600, "example": 300 }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true } } } } } } ], "properties": { "id": { "type": "string", "description": "The alert policy ID.", "minLength": 1, "example": "509fd356-df70-480b-8622-c38e27cfdd99" }, "created_at": { "description": "The create timestamp of an alert policy.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The update timestamp of an alert policy.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/alert/policies/{alert_policy_id}": { "parameters": [ { "name": "alert_policy_id", "in": "path", "required": true, "description": "Alert policy ID.", "schema": { "type": "string" } } ], "get": { "tags": [ "Alert" ], "summary": "Get an alert policy", "operationId": "getAlertPolicy", "description": "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.\n\n**Required IAM Permission:** Action `gateway:GetAlertPolicy`, Resource `arn:api7:gateway:alert/%s`", "responses": { "200": { "description": "Successfully retrieved the alert policy.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The definition of an alert policy.", "type": "object", "allOf": [ { "type": "object", "required": [ "name", "trigger_logical_operator", "trigger_conditions" ], "properties": { "name": { "description": "The alert policy name.", "example": "500 status alert", "type": "string", "minLength": 1, "maxLength": 100 }, "desc": { "description": "The alert policy description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enable": { "type": "boolean", "description": "If true, enable the alert policy.", "default": true }, "check_interval": { "type": "integer", "description": "The check interval for the alert policy. The unit is second.", "minimum": 1, "maximum": 86400 }, "severity": { "type": "string", "description": "The alert severity level.", "default": "medium", "enum": [ "high", "medium", "low" ] }, "trigger_logical_operator": { "type": "string", "description": "The logical relationship between multiple triggers.", "enum": [ "All", "Any" ], "default": "All" }, "trigger_conditions": { "type": "array", "description": "The alert trigger conditions.", "minItems": 1, "items": { "type": "object", "oneOf": [ { "title": "Status Code", "properties": { "event": { "type": "string", "enum": [ "number_of_status_code", "ratio_of_status_code" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "service_id": { "description": "Published service ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "Published route ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "event_config": { "type": "object", "description": "Alert event configurations.", "properties": { "duration": { "type": "integer", "description": "The duration time.", "minimum": 1, "example": 60 }, "unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" }, "http_status_code": { "type": "string", "description": "The HTTP status code.", "pattern": "[2-5]\\d{2}|[2-5]xx", "example": "500" } }, "required": [ "http_status_code", "duration", "unit" ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "larger_equal", "larger_than" ], "example": "larger_than" }, "value": { "example": 5, "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "event_config", "operator", "value", "scope" ] }, { "title": "Certificate Expiry", "properties": { "event": { "type": "string", "enum": [ "ssl_certificate_will_expire_in", "gateway_certificate_will_expire_in" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "License Expiry", "properties": { "event": { "type": "string", "enum": [ "license_will_expire_in" ], "description": "The event of the trigger." }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit" ] }, { "title": "Gateway Instance Offline", "properties": { "event": { "type": "string", "enum": [ "gateway_instance_offline" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "equal", "larger_equal", "larger_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "Data Plane Cores Exceeded", "properties": { "event": { "type": "string", "enum": [ "dp_core_exceeded" ], "description": "The event of trigger." } } }, { "title": "Numbers of Healthy Gateway Instances", "properties": { "event": { "type": "string", "enum": [ "number_of_healthy_gateway_instances" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ], "default": "less_equal" }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Bytes", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_bytes" ], "description": "The event of trigger for shared dictionary free space monitoring in bytes." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The threshold in MB to trigger the alert.", "example": 100 } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Percentage", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_percentage" ], "description": "The event of trigger for shared dictionary free space monitoring in percentage." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] } ] } }, "notifications": { "type": "array", "description": "The alert notifications.", "items": { "type": "object", "required": [ "type" ], "oneOf": [ { "title": "Email", "type": "object", "required": [ "type", "subject", "content" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "email" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "subject": { "type": "string", "description": "The email subject.", "minLength": 1, "example": "API7 Notification" }, "content": { "type": "string", "description": "The email content.", "minLength": 1, "format": "go_template", "example": "The xxx gateway group has received more than 5 responses with 500 status code in the last 60 seconds." } } }, { "title": "Webhook", "type": "object", "required": [ "type", "alert_message" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "webhook" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "alert_message": { "type": "string", "description": "The alert message.", "minLength": 1, "format": "go_template" } } } ] } }, "debug_sessions": { "type": "array", "description": "Debug session configurations to create automatically when the alert is triggered.", "items": { "type": "object", "description": "Configuration for a debug session to be automatically created when the alert is triggered.", "required": [ "max_samples", "duration_secs" ], "properties": { "max_samples": { "type": "integer", "description": "The maximum number of trace samples to collect.", "minimum": 1, "maximum": 200, "example": 100 }, "duration_secs": { "type": "integer", "description": "The duration in seconds for the debug session.", "minimum": 10, "maximum": 600, "example": 300 }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true } } } } } } ], "properties": { "id": { "type": "string", "description": "The alert policy ID.", "minLength": 1, "example": "509fd356-df70-480b-8622-c38e27cfdd99" }, "created_at": { "description": "The create timestamp of an alert policy.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The update timestamp of an alert policy.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Alert" ], "summary": "Delete an alert policy", "operationId": "deleteAlertPolicy", "description": "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.\n\n**Required IAM Permission:** Action `gateway:DeleteAlertPolicy`, Resource `arn:api7:gateway:alert/%s`", "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Alert" ], "summary": "Update an alert policy", "operationId": "putAlertPolicy", "description": "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.\n\n**Required IAM Permission:** Action `gateway:UpdateAlertPolicy`, Resource `arn:api7:gateway:alert/%s`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "trigger_logical_operator", "trigger_conditions" ], "properties": { "name": { "description": "The alert policy name.", "example": "500 status alert", "type": "string", "minLength": 1, "maxLength": 100 }, "desc": { "description": "The alert policy description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enable": { "type": "boolean", "description": "If true, enable the alert policy.", "default": true }, "check_interval": { "type": "integer", "description": "The check interval for the alert policy. The unit is second.", "minimum": 1, "maximum": 86400 }, "severity": { "type": "string", "description": "The alert severity level.", "default": "medium", "enum": [ "high", "medium", "low" ] }, "trigger_logical_operator": { "type": "string", "description": "The logical relationship between multiple triggers.", "enum": [ "All", "Any" ], "default": "All" }, "trigger_conditions": { "type": "array", "description": "The alert trigger conditions.", "minItems": 1, "items": { "type": "object", "oneOf": [ { "title": "Status Code", "properties": { "event": { "type": "string", "enum": [ "number_of_status_code", "ratio_of_status_code" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } }, "service_id": { "description": "Published service ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "Published route ID to scope the alert to.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "event_config": { "type": "object", "description": "Alert event configurations.", "properties": { "duration": { "type": "integer", "description": "The duration time.", "minimum": 1, "example": 60 }, "unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" }, "http_status_code": { "type": "string", "description": "The HTTP status code.", "pattern": "[2-5]\\d{2}|[2-5]xx", "example": "500" } }, "required": [ "http_status_code", "duration", "unit" ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "larger_equal", "larger_than" ], "example": "larger_than" }, "value": { "example": 5, "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "event_config", "operator", "value", "scope" ] }, { "title": "Certificate Expiry", "properties": { "event": { "type": "string", "enum": [ "ssl_certificate_will_expire_in", "gateway_certificate_will_expire_in" ], "description": "The event of the trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "License Expiry", "properties": { "event": { "type": "string", "enum": [ "license_will_expire_in" ], "description": "The event of the trigger." }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "day" ] } }, "required": [ "event", "operator", "value", "value_unit" ] }, { "title": "Gateway Instance Offline", "properties": { "event": { "type": "string", "enum": [ "gateway_instance_offline" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "equal", "larger_equal", "larger_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." }, "value_unit": { "type": "string", "description": "The duration unit.", "enum": [ "hour", "minute", "second", "year", "month", "day" ], "example": "second" } }, "required": [ "event", "operator", "value", "value_unit", "scope" ] }, { "title": "Data Plane Cores Exceeded", "properties": { "event": { "type": "string", "enum": [ "dp_core_exceeded" ], "description": "The event of trigger." } } }, { "title": "Numbers of Healthy Gateway Instances", "properties": { "event": { "type": "string", "enum": [ "number_of_healthy_gateway_instances" ], "description": "The event of trigger." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ], "default": "less_equal" }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Bytes", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_bytes" ], "description": "The event of trigger for shared dictionary free space monitoring in bytes." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The threshold in MB to trigger the alert.", "example": 100 } }, "required": [ "event", "scope", "operator", "value" ] }, { "title": "Shared Dict Free Space Percentage", "properties": { "event": { "type": "string", "enum": [ "shared_dict_free_space_percentage" ], "description": "The event of trigger for shared dictionary free space monitoring in percentage." }, "scope": { "type": "object", "description": "The scope of the trigger.", "properties": { "gateway_group_ids": { "type": "array", "description": "An array of gateway group IDs.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "gateway_group_labels": { "description": "Key-value pairs of gateway group labels.", "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "example": { "version": "v2", "env": "prod" } } }, "oneOf": [ { "required": [ "gateway_group_ids" ], "title": "Gateway Group IDs" }, { "required": [ "gateway_group_labels" ], "title": "Gateway Group Labels" } ] }, "operator": { "type": "string", "description": "The operator for the trigger condition.", "enum": [ "less_equal", "less_than" ] }, "value": { "type": "integer", "format": "int32", "description": "The numeric threshold to trigger to alert." } }, "required": [ "event", "scope", "operator", "value" ] } ] } }, "notifications": { "type": "array", "description": "The alert notifications.", "items": { "type": "object", "required": [ "type" ], "oneOf": [ { "title": "Email", "type": "object", "required": [ "type", "subject", "content" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "email" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "subject": { "type": "string", "description": "The email subject.", "minLength": 1, "example": "API7 Notification" }, "content": { "type": "string", "description": "The email content.", "minLength": 1, "format": "go_template", "example": "The xxx gateway group has received more than 5 responses with 500 status code in the last 60 seconds." } } }, { "title": "Webhook", "type": "object", "required": [ "type", "alert_message" ], "properties": { "type": { "type": "string", "description": "The notification type.", "enum": [ "webhook" ] }, "contact_point_ids": { "type": "array", "uniqueItems": true, "description": "An array of contact point IDs.", "items": { "minLength": 1, "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "alert_message": { "type": "string", "description": "The alert message.", "minLength": 1, "format": "go_template" } } } ] } }, "debug_sessions": { "type": "array", "description": "Debug session configurations to create automatically when the alert is triggered.", "items": { "type": "object", "description": "Configuration for a debug session to be automatically created when the alert is triggered.", "required": [ "max_samples", "duration_secs" ], "properties": { "max_samples": { "type": "integer", "description": "The maximum number of trace samples to collect.", "minimum": 1, "maximum": 200, "example": 100 }, "duration_secs": { "type": "integer", "description": "The duration in seconds for the debug session.", "minimum": 10, "maximum": 600, "example": 300 }, "sampling_rule": { "type": "array", "description": "Sampling rules in lua-resty-expr format.", "items": {}, "example": [ [ "status", ">=", 500 ] ], "nullable": true } } } } } } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "patch": { "tags": [ "Alert" ], "summary": "Patch an alert policy", "operationId": "patchAlertPolicy", "description": "Partially update an alert policy using JSON Patch (RFC 6902) operations. This is useful for targeted edits without resubmitting the full policy definition.\n\n**Required IAM Permission:** Action `gateway:UpdateAlertPolicy`, Resource `arn:api7:gateway:alert/%s`", "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/alert/policies/histories": { "get": { "tags": [ "Alert" ], "summary": "List all alert histories", "operationId": "listAlertHistory", "description": "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.\n\n**Required IAM Permission:** Action `gateway:GetAlertPolicy`, Resource `arn:api7:gateway:alert/*`", "parameters": [ { "name": "alert_policy_id", "description": "Alert policy ID.", "in": "query", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "description": "Alert severity.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "high", "medium", "low" ] } } }, { "in": "query", "name": "start_at", "description": "Start at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "in": "query", "name": "end_at", "description": "End at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } }, { "name": "order_by", "description": "Index to order alerts by.", "in": "query", "schema": { "type": "string", "default": "alert_time", "enum": [ "alert_time" ] } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of alert history entries.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of alert policy history.", "items": { "type": "object", "description": "", "properties": { "id": { "type": "string", "minLength": 1, "description": "ID of the alert.", "example": "ce6dbbb2-b8bc-4df8-b3e3-5af09c4a045f" }, "alert_policy_id": { "type": "string", "description": "Alert policy ID.", "minLength": 1, "example": "72a2186a-f249-4da1-a2ec-a186150895b2" }, "alert_policy_name": { "type": "string", "description": "The alert policy name.", "example": "500 status code" }, "trigger_gateway_groups": { "type": "array", "description": "An array of gateway groups that triggered the alerts.", "items": { "type": "object", "properties": { "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" } } } }, "severity": { "type": "string", "description": "The alert severity level.", "enum": [ "high", "medium", "low" ] }, "alert_time": { "type": "integer", "description": "The alert time." }, "alert_detail": { "type": "string", "description": "The alert detail." }, "notification_logs": { "type": "array", "description": "An array of notification logs.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "contact_point_name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test" }, "resource_type": { "type": "string", "description": "Type of notification.", "enum": [ "alert_policy", "api_product_notification" ] }, "resource_id": { "description": "The resource ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "resource_name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "description": "Notification sending status.", "enum": [ "success", "failed" ], "example": "failed" }, "send_time": { "type": "integer", "example": 1759649130, "description": "The time when the notification is sent." }, "request": { "type": "string", "description": "Request information.", "example": "{\"from\": \"test.send@api7.ai\", \"to\": \"test.receive@api7.ai\", \"subject\": \"API7 Notification\", \"content\": \"This is a test notification.\"}" }, "response": { "type": "string", "description": "Response from the server.", "example": "450 The domain must be verified in your account to send emails." } } } }, "debug_session_logs": { "type": "array", "description": "An array of logs recording the debug sessions created when the alert was triggered.", "items": { "type": "object", "description": "The result of a debug session creation attempt when an alert was triggered.", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "success": { "type": "boolean", "description": "Whether the debug session was created successfully." }, "error": { "type": "string", "description": "The error message if the debug session creation failed." }, "debug_session_id": { "description": "The ID of the debug session created. Only present when success is true.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID for which the debug session was created.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/audit_logs": { "get": { "tags": [ "Audit Logs" ], "summary": "List all audit logs", "operationId": "listAuditLogs", "description": "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.\n\n**Required IAM Permission:** Action `iam:GetAudit`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "name": "event_type", "in": "query", "description": "The event type. Event types can be looked up using the `/api/audit_logs/event_types` endpoint.", "example": "AddConsumerCredential", "schema": { "type": "string" } }, { "name": "operator_id", "description": "The user ID of the operator.", "in": "query", "schema": { "type": "string" } }, { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } }, { "name": "resource_id", "description": "The resource ID.", "in": "query", "schema": { "type": "string" } }, { "in": "query", "name": "start_at", "description": "Start at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "in": "query", "name": "end_at", "description": "End at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "event_time", "description": "Index to order audit logs by.", "enum": [ "event_time" ] } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of audit log entries.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of audit logs.", "items": { "type": "object", "properties": { "event_time": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "operator_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "operator": { "description": "Operator details.", "type": "object", "properties": { "id": { "description": "Operator ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "username": { "type": "string", "description": "Operator username.", "example": "admin" }, "name": { "type": "string", "description": "Operator name.", "example": "admin" }, "email": { "type": "string", "description": "Operator email.", "example": "test@email.com" }, "email_verified": { "type": "boolean", "description": "If true, the operator email is verified." } } }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "source": { "type": "string", "description": "Source of the alert log.", "enum": [ "dashboard", "api" ] }, "token_name": { "type": "string", "description": "The name of the token used for authentication.", "example": "docs" }, "event_type": { "description": "The event type.", "type": "string" }, "resource_id": { "description": "The resource ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ip_address": { "description": "The IP address.", "type": "string", "example": "10.15.101.5" }, "error_message": { "description": "The error message.", "type": "string", "example": "Duplicate key in test2's credentials" }, "http_request": { "type": "object", "description": "HTTP request details.", "properties": { "method": { "description": "HTTP request method.", "type": "string", "example": "POST" }, "uri": { "description": "HTTP request URI path.", "type": "string", "example": "/apisix/admin/consumers/test2/credentials?gateway_group_id=default" }, "body": { "description": "HTTP request body.", "type": "object", "example": { "name": "test", "plugins": { "key-auth": { "key": "********" } } } }, "user_agent": { "description": "HTTP request user agent.", "type": "string", "example": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36" } } }, "http_response": { "type": "object", "description": "HTTP response details.", "properties": { "status_code": { "type": "integer", "description": "HTTP response status code.", "example": 400 }, "body": { "type": "object", "description": "HTTP response body.", "example": {} } } } } } } } } ] } } } } } } }, "/api/audit_logs/config": { "get": { "tags": [ "Audit Config" ], "summary": "Get the configuration for audit logs.", "operationId": "getAuditConfig", "description": "Get the current audit logging configuration for the organization. Use this to verify how audit events are captured and retained.\n\nNo IAM permission required.", "responses": { "200": { "description": "Successfully retrieved or updated the audit log configuration.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "retention_days": { "type": "integer", "description": "The number of days to retain audit logs." } } } } } ] } } } } } } }, "/api/audit_logs/event_types": { "get": { "tags": [ "Audit Logs" ], "summary": "List all event types of audit logs", "operationId": "listAuditLogEventTypes", "description": "List supported audit event types that can be used for filtering and analysis when querying audit logs.\n\nNo IAM permission required.", "responses": { "200": { "description": "Successfully retrieved the list of audit log event types.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of event types of audit logs.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The key of the audit log event type.", "example": "UpdateContactPoint" }, "name": { "type": "string", "description": "The name of the audit log event type.", "example": "Update Contact Point" } } } } } } ] } } } } } } }, "/api/audit_logs/export": { "get": { "tags": [ "Audit Logs" ], "summary": "Export all audit logs", "operationId": "exportAuditLogs", "description": "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.\n\n**Required IAM Permission:** Action `iam:ExportAudits`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "name": "event_type", "in": "query", "description": "The event type. Event types can be looked up using the `/api/audit_logs/event_types` endpoint.", "example": "AddConsumerCredential", "schema": { "type": "string" } }, { "name": "operator_id", "description": "The user ID of the operator.", "in": "query", "schema": { "type": "string" } }, { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } }, { "name": "resource_id", "description": "The resource ID.", "in": "query", "schema": { "type": "string" } }, { "in": "query", "name": "start_at", "description": "Start at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "in": "query", "name": "end_at", "description": "End at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "in": "query", "name": "format", "required": true, "description": "Format to export.", "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "Successfully exported audit logs in the requested format.", "content": { "application/json": {}, "text/csv": {} } } } } }, "/api/tokens": { "post": { "tags": [ "Token" ], "summary": "Create a token", "operationId": "createToken", "description": "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.", "requestBody": { "content": { "application/json": { "schema": { "description": "Create a token.", "type": "object", "required": [ "name", "expires_at" ], "properties": { "name": { "type": "string", "maxLength": 40, "description": "The token name.", "example": "test-token" }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the token. `0` means the token will not expire.", "example": 1752288235 } } } } } }, "responses": { "200": { "description": "Access token created successfully. The token value is only returned once at creation time.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "id": { "description": "The token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 40, "description": "The token name.", "example": "test-token" }, "created_at": { "description": "The time when a token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the token. `0` means the token will not expire.", "example": 1752288235 }, "user_id": { "description": "The user ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "org_id": { "description": "The organization ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } }, { "type": "object", "properties": { "token": { "type": "string", "description": "The created token.", "example": "a7ee-gyb4v2Ryc2xfh9w707Z7r6IW3E0c1D7hu7x9ZT8Fxxxxx3G4Q9-5b101b5c7fc34e988f1ff9979cc191e1" } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Token" ], "summary": "List all tokens", "operationId": "listTokens", "description": "List API access tokens created for programmatic dashboard API access, with pagination, ordering, and search filters.", "parameters": [ { "name": "order_by", "in": "query", "description": "Index to order the tokens by.", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "updated_at", "expires_at" ] } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of access tokens.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of tokens.", "items": { "allOf": [ { "type": "object", "properties": { "id": { "description": "The token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 40, "description": "The token name.", "example": "test-token" }, "created_at": { "description": "The time when a token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the token. `0` means the token will not expire.", "example": 1752288235 }, "user_id": { "description": "The user ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "org_id": { "description": "The organization ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } }, { "type": "object", "properties": { "user_name": { "description": "The user name.", "example": "test-user", "type": "string", "minLength": 1, "maxLength": 100 }, "last_used_at": { "description": "The last time when the token is used.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/tokens/{token_id}": { "parameters": [ { "name": "token_id", "description": "The unique identifier of the token.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "get": { "tags": [ "Token" ], "summary": "Get a token", "operationId": "getToken", "description": "Get details of an API access token by token ID.", "responses": { "200": { "description": "Successfully retrieved the access token.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 40, "description": "The token name.", "example": "test-token" }, "created_at": { "description": "The time when a token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the token. `0` means the token will not expire.", "example": 1752288235 }, "user_id": { "description": "The user ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "org_id": { "description": "The organization ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Token" ], "summary": "Update a token", "operationId": "updateToken", "description": "Update mutable properties of an API access token, such as expiration and metadata fields.", "requestBody": { "content": { "application/json": { "schema": { "description": "Update a token.", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 40, "description": "The token name.", "example": "test-token" } } } } } }, "responses": { "200": { "description": "Successfully retrieved the access token.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 40, "description": "The token name.", "example": "test-token" }, "created_at": { "description": "The time when a token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the token. `0` means the token will not expire.", "example": 1752288235 }, "user_id": { "description": "The user ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "org_id": { "description": "The organization ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Token" ], "summary": "Delete a token", "operationId": "deleteToken", "description": "Delete an API access token and immediately revoke its ability to authenticate API requests.", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/tokens/{token_id}/regenerate": { "parameters": [ { "name": "token_id", "description": "The unique identifier of the token.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "put": { "tags": [ "Token" ], "summary": "Regenerate a token", "operationId": "regenerateToken", "description": "Regenerate the secret value of an existing API access token. Clients must replace stored credentials after regeneration.", "requestBody": { "content": { "application/json": { "schema": { "description": "Regenerate a token.", "type": "object", "required": [ "expires_at" ], "properties": { "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the token. `0` means the token will not expire.", "example": 1752288235 } } } } } }, "responses": { "200": { "description": "Access token created successfully. The token value is only returned once at creation time.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "id": { "description": "The token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "maxLength": 40, "description": "The token name.", "example": "test-token" }, "created_at": { "description": "The time when a token is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a token is updated.", "type": "integer", "minimum": 0, "example": 1742288235 }, "expires_at": { "type": "integer", "format": "int32", "description": "The expiration timestamp of the token. `0` means the token will not expire.", "example": 1752288235 }, "user_id": { "description": "The user ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "org_id": { "description": "The organization ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } }, { "type": "object", "properties": { "token": { "type": "string", "description": "The created token.", "example": "a7ee-gyb4v2Ryc2xfh9w707Z7r6IW3E0c1D7hu7x9ZT8Fxxxxx3G4Q9-5b101b5c7fc34e988f1ff9979cc191e1" } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups": { "get": { "tags": [ "Gateway Group" ], "summary": "List all gateway groups", "operationId": "listGatewayGroups", "description": "IAM Action: `gateway:GetGatewayGroup`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "name", "description": "Gateway group name.", "example": "default", "in": "query", "schema": { "minimum": 1, "type": "string" } }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of gateway groups.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of gateway groups.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "type": { "type": "string", "enum": [ "api7_gateway", "api7_ingress_controller" ] }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "Gateway group description.", "example": "Gateway group description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enforce_service_publishing": { "type": "boolean", "description": "If ture, bypass version control and rollback when updating services directly on a gateway group. \n" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "config": { "type": "object", "description": "Control plane details.", "properties": { "control_plane_key_prefix": { "type": "string", "description": "The prefix of the key in the control plane (etcd). The pattern is `/gateway_groups/{gateway_group_id}`.", "example": "/gateway_groups/us-west-1" }, "control_plane_user": { "type": "string", "description": "The etcd user.", "example": "etcd_user" }, "control_plane_password": { "type": "string", "description": "The etcd password.", "example": "safe_password" }, "image_tag": { "type": "string", "description": "The API7 gateway version.", "example": "latest" } } } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "post": { "tags": [ "Gateway Group" ], "summary": "Create a gateway group", "operationId": "createGatewayGroup", "description": "IAM Action: `gateway:CreateGatewayGroup`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "type": { "default": "api7_gateway", "type": "string", "enum": [ "api7_gateway", "api7_ingress_controller" ] }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "Gateway group description.", "example": "Gateway group description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enforce_service_publishing": { "type": "boolean", "description": "If ture, bypass version control and rollback when updating services directly on a gateway group.\n" } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "type": { "type": "string", "enum": [ "api7_gateway", "api7_ingress_controller" ] }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "Gateway group description.", "example": "Gateway group description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enforce_service_publishing": { "type": "boolean", "description": "If ture, bypass version control and rollback when updating services directly on a gateway group. \n" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "config": { "type": "object", "description": "Control plane details.", "properties": { "control_plane_key_prefix": { "type": "string", "description": "The prefix of the key in the control plane (etcd). The pattern is `/gateway_groups/{gateway_group_id}`.", "example": "/gateway_groups/us-west-1" }, "control_plane_user": { "type": "string", "description": "The etcd user.", "example": "etcd_user" }, "control_plane_password": { "type": "string", "description": "The etcd password.", "example": "safe_password" }, "image_tag": { "type": "string", "description": "The API7 gateway version.", "example": "latest" } } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/count/{resource_type}": { "get": { "tags": [ "Gateway Group" ], "summary": "Count resources by type in each gateway group", "operationId": "countResourceByGatewayGroup", "parameters": [ { "name": "resource_type", "in": "path", "required": true, "description": "Resource type.", "schema": { "type": "string", "enum": [ "ssl", "consumer", "gateway_instance" ] } } ], "responses": { "200": { "description": "Successfully retrieved the resource count per gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "items": { "allOf": [ { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "type": { "type": "string", "enum": [ "api7_gateway", "api7_ingress_controller" ] }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "Gateway group description.", "example": "Gateway group description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enforce_service_publishing": { "type": "boolean", "description": "If ture, bypass version control and rollback when updating services directly on a gateway group. \n" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "config": { "type": "object", "description": "Control plane details.", "properties": { "control_plane_key_prefix": { "type": "string", "description": "The prefix of the key in the control plane (etcd). The pattern is `/gateway_groups/{gateway_group_id}`.", "example": "/gateway_groups/us-west-1" }, "control_plane_user": { "type": "string", "description": "The etcd user.", "example": "etcd_user" }, "control_plane_password": { "type": "string", "description": "The etcd password.", "example": "safe_password" }, "image_tag": { "type": "string", "description": "The API7 gateway version.", "example": "latest" } } } } }, { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of resources." } } } ] } } } } ] } } } } } } }, "/api/gateway_groups/{gateway_group_id}/ssls/{ssl_id}/usage": { "get": { "tags": [ "Gateway Group" ], "summary": "List SSL Usage in a gateway group", "operationId": "listSSLUsages", "description": "IAM Action: `gateway:GetSSLCertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "ssl_id", "description": "The unique identifier of the SSL object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of SSL certificate usages.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of SSL Usage.", "items": { "description": "SSL usage response.", "type": "object", "allOf": [ { "type": "object", "properties": { "service_id": { "description": "ID of the service template.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "description": "Name of the service.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "upstream_name": { "type": "string", "description": "Name of the upstream that uses SSL.", "example": "sample-upstream" }, "ssl_id": { "type": "string", "description": "ID of the SSL that upstream uses.", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/snis/{sni_id}/usage": { "get": { "tags": [ "Gateway Group" ], "summary": "List SNI Usage in a gateway group", "operationId": "listSNIUsages", "description": "IAM Action: `gateway:GetSNI`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "sni_id", "description": "The unique identifier of the SNI object.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of SNI usages.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of SNI Usage.", "items": { "type": "object", "properties": { "service_id": { "description": "ID of the service template.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "description": "Name of the service.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "hosts": { "type": "array", "description": "Hostnames related to the SNIs.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/certificates/{certificate_id}/usage": { "get": { "tags": [ "Gateway Group" ], "summary": "List Certificate Usage in a gateway group", "operationId": "listCertificateUsages", "description": "IAM Action: `gateway:GetCertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s` ", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "certificate_id", "description": "The unique identifier of the Certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "resource_type", "in": "query", "required": false, "description": "Type of resource referencing the certificate.", "schema": { "type": "string", "enum": [ "sni", "upstream" ], "default": "sni" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of certificate usages.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of certificate usages.", "items": { "oneOf": [ { "title": "SNI", "type": "object", "properties": { "sni_id": { "description": "ID of the SNI.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "sni_name": { "type": "string", "description": "Name of the SNI.", "example": "sample-sni" }, "service_id": { "description": "ID of the service template.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "description": "Name of the service.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "hosts": { "type": "array", "description": "Hostnames related to the SNIs.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } }, { "title": "Upstream", "type": "object", "properties": { "upstream_id": { "type": "string", "description": "Upstream ID.", "example": "ecb86508-7484-4298-9440-ac7a60116997" }, "upstream_name": { "type": "string", "description": "Name of the upstream that uses SSL.", "example": "sample-upstream" }, "service_id": { "description": "ID of the service template.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "description": "Name of the service.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/ca_certificates/{ca_certificate_id}/usage": { "get": { "tags": [ "Gateway Group" ], "summary": "List CA Certificate Usage in a gateway group", "operationId": "listCACertificateUsages", "description": "IAM Action: `gateway:GetCACertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "ca_certificate_id", "description": "The unique identifier of the certificate.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "resource_type", "in": "query", "required": false, "description": "Type of resource referencing the certificate.", "schema": { "type": "string", "enum": [ "sni", "upstream" ], "default": "sni" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of CA certificate usages.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of CA certificate usages.", "items": { "oneOf": [ { "title": "SNI", "type": "object", "properties": { "sni_id": { "description": "ID of the SNI.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "sni_name": { "type": "string", "description": "Name of the SNI.", "example": "sample-sni" }, "service_id": { "description": "ID of the service template.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "description": "Name of the service.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "hosts": { "type": "array", "description": "Hostnames related to the SNIs.", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } } }, { "title": "Upstream", "type": "object", "properties": { "upstream_id": { "type": "string", "description": "Upstream ID.", "example": "ecb86508-7484-4298-9440-ac7a60116997" }, "upstream_name": { "type": "string", "description": "Name of the upstream that uses SSL.", "example": "sample-upstream" }, "service_id": { "description": "ID of the service template.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "description": "Name of the service.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/certificates/exists": { "post": { "tags": [ "Gateway Group" ], "summary": "Check if a certificate exists in a gateway group", "description": "IAM Action: `gateway:GetCACertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "operationId": "checkCertificateExists", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved the certificate.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "description": "Certificate.", "oneOf": [ { "title": "Certificate Reference", "description": "Path to the certificate in environment variable or secret manager.", "type": "string", "pattern": "^\\$(secret|env|ENV)://", "example": "$secret://aws/john/apisix-secrets/john-key-auth" }, { "title": "Certificate Content", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ] }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "common_name": { "type": "string", "description": "The common name of the certificate.", "example": "example.com" }, "subject_alt_names": { "type": "array", "description": "The subject alternative names of the certificate.", "items": { "type": "string", "example": "www.example.com" } }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string", "example": "1cf56bfe-7727-4584-93f2-9d09271bd42a" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/ca_certificates/exists": { "post": { "tags": [ "Gateway Group" ], "summary": "Check if a CA certificate exists in a gateway group", "description": "IAM Action: `gateway:GetCACertificate`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "operationId": "checkCACertificateExists", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } } } } } }, "responses": { "200": { "description": "Successfully retrieved the CA certificate.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The Certificate response format, with filtering the sensitive fields\nand some other fields.", "type": "object", "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "associated_snis": { "type": "array", "description": "The SNI IDs associated with the certificate.", "items": { "type": "string" } }, "exptime": { "type": "integer", "description": "The SSL certificate expire time.", "example": 1735680000 }, "validity_start": { "type": "integer", "description": "The earliest time when the SSL certificate is used.", "example": 1714540800 }, "validity_end": { "type": "integer", "description": "The latest time when the SSL certificate is used.", "example": 1730419200 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/secret_providers/{secret_provider}/{secret_provider_id}/usage": { "get": { "tags": [ "Gateway Group" ], "summary": "List Secret Provider Usage in a gateway group", "operationId": "listSecretProviderUsages", "description": "IAM Action: `gateway:GetSecretProvider`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "secret_provider", "description": "Secret provider.", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "vault", "aws", "kubernetes" ] } }, { "name": "secret_provider_id", "description": "Secret provider ID.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "resource_type", "in": "query", "required": false, "description": "Resource type.", "schema": { "type": "string", "enum": [ "consumer", "service", "route", "ssl", "global_rule", "consumer_credential", "certificate" ] } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of secret provider usages.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of Secret Usage.", "items": { "description": "secret usage response", "type": "object", "allOf": [ { "type": "object", "properties": { "parent_id": { "type": "string", "description": "Parent ID, availble for `route` and `consumer_credential` resource types. For instance, when the resource type is `route`, the parent ID is the service ID.", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "resource_type": { "type": "string", "description": "Type of the resource that uses secret.", "example": "route" }, "resource_id": { "description": "ID of the resource that uses secret.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "resource_name": { "description": "Resource name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "field": { "type": "string", "description": "Field in the resource that references the secret.", "example": "key-auth/key" }, "id": { "description": "ID of the secret provider.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "secret_manager": { "type": "string", "description": "Secret manager.", "enum": [ "vault", "aws", "kubernetes" ], "example": "vault" } } }, { "type": "object", "properties": { "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}": { "delete": { "tags": [ "Gateway Group" ], "summary": "Delete a gateway group", "operationId": "deleteGatewayGroup", "description": "IAM Action: `gateway:DeleteGatewayGroup`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "Gateway Group" ], "summary": "Update a gateway group", "operationId": "putGatewayGroup", "description": "IAM Action: `gateway:UpdateGatewayGroup`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "Gateway group description.", "example": "Gateway group description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } } }, "required": true }, "responses": { "200": { "description": "Successfully retrieved or modified the gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "type": { "type": "string", "enum": [ "api7_gateway", "api7_ingress_controller" ] }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "Gateway group description.", "example": "Gateway group description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enforce_service_publishing": { "type": "boolean", "description": "If ture, bypass version control and rollback when updating services directly on a gateway group. \n" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "config": { "type": "object", "description": "Control plane details.", "properties": { "control_plane_key_prefix": { "type": "string", "description": "The prefix of the key in the control plane (etcd). The pattern is `/gateway_groups/{gateway_group_id}`.", "example": "/gateway_groups/us-west-1" }, "control_plane_user": { "type": "string", "description": "The etcd user.", "example": "etcd_user" }, "control_plane_password": { "type": "string", "description": "The etcd password.", "example": "safe_password" }, "image_tag": { "type": "string", "description": "The API7 gateway version.", "example": "latest" } } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "get": { "tags": [ "Gateway Group" ], "summary": "Get a gateway group", "operationId": "getGatewayGroup", "description": "IAM Action: `gateway:GetGatewayGroup`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved or modified the gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "type": { "type": "string", "enum": [ "api7_gateway", "api7_ingress_controller" ] }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "Gateway group description.", "example": "Gateway group description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "enforce_service_publishing": { "type": "boolean", "description": "If ture, bypass version control and rollback when updating services directly on a gateway group. \n" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "config": { "type": "object", "description": "Control plane details.", "properties": { "control_plane_key_prefix": { "type": "string", "description": "The prefix of the key in the control plane (etcd). The pattern is `/gateway_groups/{gateway_group_id}`.", "example": "/gateway_groups/us-west-1" }, "control_plane_user": { "type": "string", "description": "The etcd user.", "example": "etcd_user" }, "control_plane_password": { "type": "string", "description": "The etcd password.", "example": "safe_password" }, "image_tag": { "type": "string", "description": "The API7 gateway version.", "example": "latest" } } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/admin_key": { "get": { "tags": [ "Gateway Group" ], "summary": "Get the admin key for a gateway group.", "operationId": "getAdminKey", "description": "IAM Action: `gateway:GetAdminKey`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Admin API key generated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "key": { "type": "string", "description": "The admin key in plain text.", "example": "a7ee-iBTTIAOm76y2Q7h2xxxxx1uCyVQ3HY36l6hH98igxxxxxx-a591ad8b17db4f88b24b3c5602356971" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "default": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } } } }, "put": { "tags": [ "Gateway Group" ], "summary": "Generate an admin key for a gateway group", "operationId": "generateAdminKey", "description": "IAM Action: `gateway:UpdateGatewayGroup`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Admin API key generated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "key": { "type": "string", "description": "The admin key in plain text.", "example": "a7ee-iBTTIAOm76y2Q7h2xxxxx1uCyVQ3HY36l6hH98igxxxxxx-a591ad8b17db4f88b24b3c5602356971" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/deployment/docker": { "get": { "tags": [ "Gateway Group", "Gateway Instance" ], "summary": "Generate a script to install the gateway instance by Docker", "operationId": "generateInstallScriptForDocker", "description": "IAM Action: `gateway:CreateGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "dp_manager_address", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The IP address of the control plane.", "example": "10.15.101.5" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "validity_period", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } }, { "name": "image", "in": "query", "required": false, "description": "Docker image.", "schema": { "type": "string", "minLength": 1 }, "example": "api7/api7-ee-3-gateway" }, { "name": "http_port", "in": "query", "required": false, "description": "The HTTP port of the gateway.", "schema": { "type": "integer", "default": 9080 } }, { "name": "https_port", "in": "query", "required": false, "description": "The HTTPS port of the gateway.", "schema": { "type": "integer", "default": 9443 } }, { "name": "name", "in": "query", "required": false, "description": "The hostname of the gateway.", "schema": { "type": "string", "minLength": 1 } }, { "name": "extra_args[]", "description": "Additional docker run arguments.", "in": "query", "required": false, "style": "form", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "a=b", "c=d" ] } ], "responses": { "200": { "description": "Successfully generated the Docker run command for data plane installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "docker run -d -e API7_CONTROL_PLANE_ENDPOINTS='[\"https://12.12.123.123:31344\"]' \\\n -e API7_GATEWAY_GROUP_SHORT_ID=tabqbdwnahkqo \\\n -e API7_CONTROL_PLANE_CERT=\"-----BEGIN CERTIFICATE-----\n MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\n ...\n -----END CERTIFICATE-----\" \\\n -e API7_CONTROL_PLANE_KEY=\"-----BEGIN PRIVATE KEY-----\n MC4CAQAwBQYDK2VwBCIEIG1Q/eJDdTZ4krnd7ezprKcZ2ASeTSrhpWglMzh9d0Hs\n -----END PRIVATE KEY-----\" \\\n -e API7_CONTROL_PLANE_CA=\"-----BEGIN CERTIFICATE-----\n MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE\n ...\n -----END CERTIFICATE-----\" \\\n -e API7_CONTROL_PLANE_SNI=\"api7ee3-dp-manager\" \\\n -p 9080:9080 \\\n -p 9443:9443 \\\n api7/api7-ee-3-gateway:latest\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/deployment/docker-compose": { "get": { "tags": [ "Gateway Group", "Gateway Instance" ], "summary": "Generate a script to install the gateway instance by Docker Compose", "operationId": "generateInstallScriptForDockerCompose", "description": "IAM Action: `gateway:CreateGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "dp_manager_address", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The IP address of the control plane.", "example": "10.15.101.5" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "validity_period", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } }, { "name": "image", "in": "query", "required": false, "description": "Docker image.", "schema": { "type": "string", "minLength": 1 }, "example": "api7/api7-ee-3-gateway" }, { "name": "http_port", "in": "query", "required": false, "description": "The HTTP port of the gateway.", "schema": { "type": "integer", "default": 9080 } }, { "name": "https_port", "in": "query", "required": false, "description": "The HTTPS port of the gateway.", "schema": { "type": "integer", "default": 9443 } }, { "name": "name", "in": "query", "required": false, "description": "The name of the docker compose container and service.", "schema": { "type": "string", "default": "api7-ee-3-gateway", "minLength": 1 } }, { "name": "extra_args[]", "description": "Additional docker run arguments.", "in": "query", "required": false, "style": "form", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "a=b", "c=d" ] } ], "responses": { "200": { "description": "Successfully generated the Docker Compose configuration for data plane installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "services:\n gateway:\n image: api7/api7-ee-3-gateway:latest\n container_name: gateway\n hostname: gateway\n restart: always\n ports:\n - \"9080:9080\"\n - \"9443:9443\"\n environment:\n API7_DP_MANAGER_ENDPOINTS: '[\"https://12.12.123.123:31344\"]'\n API7_GATEWAY_GROUP_SHORT_ID: \"oybqauztthfao\"\n API7_DP_MANAGER_SNI: \"api7ee3-dp-manager\"\n API7_DP_MANAGER_CERT: |\n -----BEGIN CERTIFICATE-----\n MIIBhjCCATigAwIBAgICBAAwBQYDK2VwMEQxCzAJBgNVBAYTAlVTMRMwEQYDVQQI\n ...\n -----END CERTIFICATE-----\n\n API7_DP_MANAGER_KEY: |\n -----BEGIN PRIVATE KEY-----\n MC4CAQAwBQYDK2VwBCIEINc8Pn0gPTq2keIBs4tzdemXxhe1Qq7xAxtJ8nve6Mg3\n -----END PRIVATE KEY-----\n\n API7_CONTROL_PLANE_CA: |\n -----BEGIN CERTIFICATE-----\n MIIBdTCCASegAwIBAgIQVXqTFu/hH4caZptKdGp04zAFBgMrZXAwRDELMAkGA1UE\n ...\n -----END CERTIFICATE-----\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/deployment/helm/script": { "get": { "tags": [ "Gateway Group", "Gateway Instance" ], "summary": "Generate a script to install the gateway instance by Helm in Kubernetes", "operationId": "generateInstallScriptForHelm", "description": "IAM Action: `gateway:CreateGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "dp_manager_address", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The IP address of the control plane.", "example": "10.15.101.5" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "validity_period", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } }, { "name": "name", "in": "query", "required": true, "description": "Gateway name.", "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "required": true, "description": "Gateway namespace.", "schema": { "type": "string" } }, { "name": "service_account", "in": "query", "required": false, "description": "Service account to install the gateway.", "schema": { "type": "string" } }, { "name": "replicas", "in": "query", "required": false, "description": "The number of replicas.", "schema": { "type": "integer", "default": 1 } }, { "name": "workers", "in": "query", "required": false, "description": "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.", "example": 5, "schema": { "type": "integer" } }, { "name": "cpu_limit", "in": "query", "required": false, "description": "The CPU limit in number of cores.", "example": "6", "schema": { "type": "string" } }, { "name": "memory_limit", "in": "query", "required": false, "description": "The memory limit. Use the format ``.", "example": "6Gi", "schema": { "type": "string" } }, { "name": "extra_values[]", "in": "query", "description": "Extra values to be passed to the Helm chart, in the form of `key=value`.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "a=b", "c=d" ] } ], "responses": { "200": { "description": "Successfully generated the Helm install script for data plane installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "helm repo add api7 https://charts.api7.ai\nhelm repo update\ncat > /tmp/tls.crt < /tmp/tls.key < /tmp/ca.crt <`.", "example": "6Gi", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully generated the Helm values YAML for data plane installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "apiVersion: v1\ndata:\n tls.crt: LS0tLS1CRUdJTiB...\n tls.key: LS0tLS1CRUdJTiB...\n ca.crt: LS0tLS1CRUdJTiB...\nkind: Secret\nmetadata:\n name: name-tls\n namespace: default\ntype: kubernetes.io/tls\n---\napisix:\n replicaCount: 1\n image:\n repository: api7/api7-ee-3-gateway\n tag: dev\n extraEnvVars:\n - name: API7_GATEWAY_GROUP_SHORT_ID\n value: \"tabqbdwnahkqo\"\netcd:\n host:\n - \"https://12.12.123.123:31344\"\n auth:\n tls:\n enabled: true\n existingSecret: name-tls\n certFilename: tls.crt\n certKeyFilename: tls.key\n sni: api7ee3-dp-manager\n verify: true\ngateway:\n tls:\n existingCASecret: name-tls\n certCAFilename: ca.crt\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/ingress/script": { "get": { "tags": [ "Gateway Group" ], "summary": "Generate a script to install gateway API resources for ingress gateway group", "operationId": "generateInstallIngressScript", "description": "IAM Action: `gateway:GetAdminKey`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "name", "in": "query", "required": true, "description": "Ingress resource name.", "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "required": true, "description": "Namespace to install the ingress resources.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gateway-api", "ingress", "ingress-v1beta1" ], "default": "gateway-api" } } ], "responses": { "200": { "description": "Successfully generated the Kubernetes Gateway API manifest for data plane installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "kubectl create namespace default --dry-run=client -o yaml | kubectl apply -f -\necho \"\n---\napiVersion: gateway.networking.k8s.io/v1\nkind: GatewayClass\nmetadata:\n name: apisix\nspec:\n controllerName: apisix.apache.org/apisix-ingress-controller\n---\napiVersion: apisix.apache.org/v1alpha1\nkind: GatewayProxy\nmetadata:\n name: name\nspec:\n provider:\n type: ControlPlane\n controlPlane:\n endpoints:\n - [\"12.12.123.123\"]\n auth:\n type: AdminKey\n adminKey:\n value: a7adm-ZgR85iE...\n---\napiVersion: gateway.networking.k8s.io/v1\nkind: Gateway\nmetadata:\n name: apisix\nspec:\n gatewayClassName: apisix\n listeners:\n - name: http\n protocol: HTTP\n port: 80\n infrastructure:\n parametersRef:\n group: apisix.apache.org\n kind: GatewayProxy\n name: name\n\" | kubectl apply -f - -n default\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/ingress/step1": { "get": { "tags": [ "Gateway Group" ], "summary": "Generate script to install the gateway api resources for ingress gateway group.", "operationId": "generateInstallIngressStep1", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "namespace", "in": "query", "description": "Namespace to install the ingress controller.", "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "Helm release name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully generated the ingress controller installation script.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "default": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/instances/{gateway_instance_id}": { "delete": { "tags": [ "Gateway Instance" ], "summary": "Delete gateway instance", "operationId": "deleteGatewayInstance", "description": "IAM Action: `gateway:DeleteGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_instance_id", "in": "path", "required": true, "description": "Gateway instance ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/dp_client_certificates": { "post": { "tags": [ "Gateway Instance", "Gateway Group" ], "summary": "Issue a data plane certificate on a gateway group", "operationId": "issueDataplaneCertificate", "description": "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.\n\n**Required IAM Permission:** Action `gateway:CreateGatewayInstance`, Resource `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "validity_period": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } } } } } }, "responses": { "200": { "description": "Data plane certificate issued successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "Certificate ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "certificate": { "type": "string", "description": "Certificate content.", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n" }, "private_key": { "type": "string", "description": "Private key content.", "example": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n" }, "expiry": { "description": "Expiration of the certificate.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } ] } } } } } } }, "/api/gateway_groups/{gateway_group_id}/services": { "get": { "tags": [ "Gateway Group", "Published Service" ], "deprecated": true, "summary": "List all published services in a gateway group", "operationId": "listPublishedServicesDeprecated", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s` Deprecated, you can use `GET /apisix/admin/services` for instead.", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "unhealthy_nodes", "description": "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.", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "unhealthy_nodes_exists", "no_unhealthy_nodes" ] } } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order published services by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "publish_time", "name" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "hosts", "in": "query", "schema": { "type": "array", "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } } }, { "name": "type", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "http", "stream" ] } } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of published services in the gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of published services.", "items": { "allOf": [ { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "unhealthy_nodes_count": { "type": "integer", "description": "Unhealthy nodes count.", "example": 0 }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Get a published service on a gateway group", "operationId": "getPublishedServiceByServiceTemplateID", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the published service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "unhealthy_nodes_count": { "type": "integer", "description": "Unhealthy nodes count.", "example": 0 }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "delete": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Delete a published service on a gateway group", "operationId": "deletePublishedServiceByServiceTemplateID", "description": "IAM Action: `gateway:DeletePublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/oas": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Get the OpenAPI Specification of a published service on a gateway group", "operationId": "getPublishedServiceOASByServiceTemplateID", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the OpenAPI specification for the service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI spec of the service.", "example": "Raw OpenAPI spec" }, "api_count": { "type": "integer", "description": "The number of APIs in the service.", "example": 10 }, "api_desc": { "type": "string", "description": "The description of the OAS.", "example": "OAS description." } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Update the OpenAPI Specification of a published service on a gateway group", "operationId": "putPublishedServiceOASByServiceTemplateID", "description": "IAM Action: `gateway:UpdatePublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI spec of the service.", "example": "Raw OpenAPI spec" } } } } } }, "responses": { "200": { "description": "Successfully retrieved the OpenAPI specification for the service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI spec of the service.", "example": "Raw OpenAPI spec" }, "api_count": { "type": "integer", "description": "The number of APIs in the service.", "example": 10 }, "api_desc": { "type": "string", "description": "The description of the OAS.", "example": "OAS description." } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/routes": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "List all routes of published service on a gateway group", "operationId": "listPublishedServiceRoutesByServiceTemplateID", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of routes in the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of route versions.", "items": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/routes/{route_template_id}": { "get": { "tags": [ "Gateway Group", "Published Service", "Route" ], "summary": "Get a route in a published service on a gateway group", "operationId": "getPublishedServiceRouteByServiceTemplateID", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "route_template_id", "description": "The unique identifier of the route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the route from the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/routes/{route_template_id}/runtime_configuration": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Get the runtime configuration of a route in a published service on a gateway group", "operationId": "getPublishedRouteRuntimeConfiguration", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "route_template_id", "description": "The unique identifier of the route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the runtime configuration for the published route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "patch": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Update the runtime configuration of a route in a published service on a gateway group", "operationId": "patchPublishedRouteRuntimeConfiguration", "description": "IAM Action: `gateway:UpdatePublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "route_template_id", "description": "The unique identifier of the route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Successfully retrieved the runtime configuration for the published route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/stream_routes": { "get": { "tags": [ "Gateway Group", "Published Service", "Stream Route" ], "summary": "List all stream routes of a published service on a gateway group", "operationId": "listPublishedServiceStreamRoutesByServiceTemplateID", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of stream routes in the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of route versions.", "items": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "stream_route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/stream_routes/{stream_route_template_id}": { "get": { "tags": [ "Gateway Group", "Published Service", "Stream Route" ], "summary": "Get a stream route in a published service on a gateway group", "operationId": "getPublishedServiceStreamRouteByServiceTemplateID", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "stream_route_template_id", "description": "The unique identifier of the stream route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the stream route from the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "stream_route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/stream_routes/{stream_route_template_id}/runtime_configuration": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Get the runtime configuration of a stream route in a published service on a gateway group", "operationId": "getPublishedStreamRouteRuntimeConfiguration", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "stream_route_template_id", "description": "The unique identifier of the stream route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the runtime configuration for the published stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "patch": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Update the runtime configuration of a stream route in a published service on a gateway group", "operationId": "patchPublishedStreamRouteRuntimeConfiguration", "description": "IAM Action: `gateway:UpdatePublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "stream_route_template_id", "description": "The unique identifier of the stream route in the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Successfully retrieved the runtime configuration for the published stream route.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/versions": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "List all history versions of a published services on a gateway group by service ID", "operationId": "listPublishedServiceVersions", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "publish_time", "enum": [ "publish_time" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of published service versions.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of published service versions.", "items": { "allOf": [ { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "publish_time": { "description": "The time when a service version is published.", "type": "integer", "minimum": 0, "example": 1742288232 } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/runtime_configuration": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Get service runtime configurations of a published service on a gateway group", "operationId": "getServiceRuntimeConfiguration", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the runtime configuration for the published service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "oneOf": [ { "type": "object", "minProperties": 1, "properties": { "hosts": { "type": "array", "description": "The hosts of the service to accept incoming requests.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "path_prefix": { "maxLength": 4096, "minLength": 1, "pattern": "^/", "type": "string", "description": "The listening path prefix of the service.", "example": "/test" }, "strip_path_prefix": { "type": "boolean", "default": true, "description": "If true, strip the path prefix when proxying the request to the upstream." }, "upstream": { "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "minProperties": 1, "properties": { "upstream": { "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "patch": { "tags": [ "Gateway Group", "Published Service" ], "summary": "Update service runtime configurations of a published service on a gateway group", "operationId": "patchServiceRuntimeConfiguration", "description": "IAM Action: `gateway:UpdatePublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "in": "query", "name": "dry-run", "schema": { "type": "string", "enum": [ "all" ] }, "description": "When specified, run the operation in dry-run mode." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Successfully retrieved the runtime configuration for the published service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "oneOf": [ { "type": "object", "minProperties": 1, "properties": { "hosts": { "type": "array", "description": "The hosts of the service to accept incoming requests.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "path_prefix": { "maxLength": 4096, "minLength": 1, "pattern": "^/", "type": "string", "description": "The listening path prefix of the service.", "example": "/test" }, "strip_path_prefix": { "type": "boolean", "default": true, "description": "If true, strip the path prefix when proxying the request to the upstream." }, "upstream": { "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, { "type": "object", "minProperties": 1, "properties": { "upstream": { "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/services/{service_template_id}/healthcheck": { "get": { "tags": [ "Gateway Group", "Published Service" ], "summary": "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", "operationId": "getUpstreamHealthcheckStatus", "description": "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.\n\n**Required IAM Permission:** Action `gateway:GetPublishedService`, Resource `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "upstream_id", "description": "The unique identifier of the upstream.", "in": "query", "required": false, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "The response for retrieving some source's healthcheck status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "Healthcheck status data for every node.", "additionalProperties": { "title": "Upstream Service", "type": "object", "description": "Node's healthcheck status on every gateway instance group by node.", "properties": { "host": { "type": "string", "example": "httpbin.com", "description": "Upstream host." }, "port": { "type": "integer", "example": 80, "description": "Upstream port." }, "total": { "type": "integer", "description": "Total number of gateway instances.", "example": 1 }, "healthy": { "type": "integer", "description": "Number of gateway instances that determine the node is healthy.", "example": 1 }, "unhealthy": { "type": "integer", "description": "Number of gateway instances that determine the node is unhealthy." }, "unknown": { "type": "integer", "description": "Number of gateway instances that did not report the check results for this node." }, "updated_at": { "description": "The time of the node status updated at.", "type": "integer", "minimum": 0, "example": 1742288235 }, "gateway_instances": { "type": "array", "description": "An array of gateway instance's health check count details of the node.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Gateway instance ID.", "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "hostname": { "type": "string", "description": "Instance hostname.", "example": "api7ee3-apisix-699b68db7f-cxgcw" }, "status": { "type": "string", "description": "Health status of the node.", "enum": [ "healthy", "unhealthy", "unknown" ], "example": "healthy" }, "created_at": { "description": "The timestamp of the data plane’s first report of the gateway instance’s probe result regarding the node’s health status.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The timestamp of the most recent report from the data plane on the gateway instance’s probe result for the node’s health status.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } }, "example": { "httpbin.com:80": { "host": "httpbin.com", "port": 80, "total": 1, "healthy": 1, "unhealthy": 0, "unknown": 0, "updated_at": 1750150319, "gateway_instances": [ { "id": "xxx-yyy-zzz", "hostname": "api7ee3-apisix-699b68db7f-cxgcw", "status": "healthy", "created_at": 1750150300, "updated_at": 1750150335 } ] } } } } } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "List all service registry connections on a gateway group", "operationId": "listServiceRegistries", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order service registry connections by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "last_connect_time" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of service registries.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of service registries.", "items": { "allOf": [ { "description": "The service registry model.", "allOf": [ { "type": "object", "required": [ "name", "type" ], "allOf": [ { "type": "object", "properties": { "name": { "example": "sample-service-registry", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "description": "Service registry description.", "example": "service registry description" }, "health_check": { "type": "object", "description": "Health check configurations.", "properties": { "probe_interval": { "default": 15, "minimum": 1, "type": "integer", "format": "int32", "description": "The time interval for checking service registry (in seconds)." }, "probe_timeout": { "default": 5, "minimum": 1, "type": "integer", "format": "int32", "description": "The timeout for checking service registry (in seconds)." } } } } }, { "oneOf": [ { "title": "Kubernetes", "type": "object", "required": [ "type", "kubernetes_config" ], "properties": { "type": { "type": "string", "enum": [ "kubernetes" ], "description": "The kubernetes service type." }, "kubernetes_config": { "type": "object", "description": "Kubernetes service registry configurations.", "properties": { "service": { "description": "The IP address of the Kubernetes API server.", "type": "object", "required": [ "schema", "host", "port" ], "properties": { "schema": { "type": "string", "enum": [ "http", "https" ] }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "string", "minLength": 1, "example": "6443" } } }, "namespace_selector": { "description": "The namespace selector to filter target namespaces.", "type": "object", "nullable": true, "properties": { "equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to match namespaces whose name is exactly equal to the specified string.", "example": "prod" }, "not_equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to exclude namespaces whose name is exactly equal to the specified string.", "example": "kube-system" }, "match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to match namespaces whose names match any of the specified strings.", "example": [ "team-a" ] }, "not_match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to exclude namespaces whose names match any of the specified strings.", "example": [ "test-env" ] } }, "oneOf": [ { "title": "Equal", "required": [ "equal" ] }, { "title": "Not Equal", "required": [ "not_equal" ] }, { "title": "Match", "required": [ "match" ] }, { "title": "Not Match", "required": [ "not_match" ] } ] }, "label_selector": { "description": "The label selector to filter target endpoints.", "type": "string", "example": "app=nginx,env=prod" }, "client": { "description": "The client name.", "oneOf": [ { "title": "Token File", "properties": { "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "pattern": "^[^\\:*?\"<>|]*$", "example": "/var/run/secrets/kubernetes.io/serviceaccount/token" } }, "required": [ "token_file" ] }, { "title": "Token Value", "properties": { "token": { "description": "The token of the Kubernetes service account.", "type": "string", "pattern": "^[A-Za-z0-9+\\/._=-]+$" } }, "required": [ "token" ] } ] } } } } }, { "title": "Nacos", "type": "object", "required": [ "type", "nacos_config" ], "properties": { "type": { "type": "string", "enum": [ "nacos" ], "description": "The Nacos service type." }, "nacos_config": { "type": "object", "required": [ "hosts" ], "description": "Nacos service registry configurations.", "properties": { "hosts": { "description": "The address of the Nacos API server.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 } }, "prefix": { "description": "The prefix of the Nacos API.", "type": "string", "default": "/nacos/v1" }, "default_weight": { "type": "integer", "description": "The default weight of the endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 10 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Nacos, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } }, "auth": { "description": "Nacos authentication configuration.", "oneOf": [ { "title": "Username & Password", "properties": { "username": { "description": "The username of the Nacos API.", "type": "string", "minLength": 1, "example": null }, "password": { "description": "The password of the Nacos API.", "type": "string", "minLength": 1, "example": null } }, "required": [ "username", "password" ] }, { "title": "Token", "properties": { "token": { "type": "string", "description": "The token of the Nacos service.", "minLength": 1 } }, "required": [ "token" ] }, { "title": "Access Key & Secret Key", "properties": { "access_key": { "description": "The access key of the Nacos API.", "type": "string", "minLength": 1 }, "secret_key": { "description": "The secret key of the Nacos API.", "type": "string", "minLength": 1 } }, "required": [ "access_key", "secret_key" ] } ] } } } } }, { "title": "Consul", "type": "object", "required": [ "type", "consul_config" ], "properties": { "type": { "type": "string", "enum": [ "consul" ], "description": "The Consul service type." }, "consul_config": { "type": "object", "required": [ "servers" ], "description": "Consul service registry configurations.", "properties": { "servers": { "description": "The addresses of the Consul servers.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 }, "example": [ "http://127.0.0.1:8500" ] }, "token": { "description": "The ACL token for authenticating with Consul.", "type": "string" }, "weight": { "type": "integer", "description": "The default weight of the discovered endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 30 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Consul, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } } } } } } ] } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "lost_connection", "connecting" ], "default": "connecting", "description": "The status of the service registry." }, "last_connect_time": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "associated_services_count": { "type": "integer", "format": "int32", "description": "The associated services of the service registry." } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "post": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "Create a service registry connection on a gateway group", "operationId": "createServiceRegistry", "description": "IAM Action: `gateway:ConnectServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type" ], "allOf": [ { "type": "object", "properties": { "name": { "example": "sample-service-registry", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "description": "Service registry description.", "example": "service registry description" }, "health_check": { "type": "object", "description": "Health check configurations.", "properties": { "probe_interval": { "default": 15, "minimum": 1, "type": "integer", "format": "int32", "description": "The time interval for checking service registry (in seconds)." }, "probe_timeout": { "default": 5, "minimum": 1, "type": "integer", "format": "int32", "description": "The timeout for checking service registry (in seconds)." } } } } }, { "oneOf": [ { "title": "Kubernetes", "type": "object", "required": [ "type", "kubernetes_config" ], "properties": { "type": { "type": "string", "enum": [ "kubernetes" ], "description": "The kubernetes service type." }, "kubernetes_config": { "type": "object", "description": "Kubernetes service registry configurations.", "properties": { "service": { "description": "The IP address of the Kubernetes API server.", "type": "object", "required": [ "schema", "host", "port" ], "properties": { "schema": { "type": "string", "enum": [ "http", "https" ] }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "string", "minLength": 1, "example": "6443" } } }, "namespace_selector": { "description": "The namespace selector to filter target namespaces.", "type": "object", "nullable": true, "properties": { "equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to match namespaces whose name is exactly equal to the specified string.", "example": "prod" }, "not_equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to exclude namespaces whose name is exactly equal to the specified string.", "example": "kube-system" }, "match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to match namespaces whose names match any of the specified strings.", "example": [ "team-a" ] }, "not_match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to exclude namespaces whose names match any of the specified strings.", "example": [ "test-env" ] } }, "oneOf": [ { "title": "Equal", "required": [ "equal" ] }, { "title": "Not Equal", "required": [ "not_equal" ] }, { "title": "Match", "required": [ "match" ] }, { "title": "Not Match", "required": [ "not_match" ] } ] }, "label_selector": { "description": "The label selector to filter target endpoints.", "type": "string", "example": "app=nginx,env=prod" }, "client": { "description": "The client name.", "oneOf": [ { "title": "Token File", "properties": { "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "pattern": "^[^\\:*?\"<>|]*$", "example": "/var/run/secrets/kubernetes.io/serviceaccount/token" } }, "required": [ "token_file" ] }, { "title": "Token Value", "properties": { "token": { "description": "The token of the Kubernetes service account.", "type": "string", "pattern": "^[A-Za-z0-9+\\/._=-]+$" } }, "required": [ "token" ] } ] } } } } }, { "title": "Nacos", "type": "object", "required": [ "type", "nacos_config" ], "properties": { "type": { "type": "string", "enum": [ "nacos" ], "description": "The Nacos service type." }, "nacos_config": { "type": "object", "required": [ "hosts" ], "description": "Nacos service registry configurations.", "properties": { "hosts": { "description": "The address of the Nacos API server.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 } }, "prefix": { "description": "The prefix of the Nacos API.", "type": "string", "default": "/nacos/v1" }, "default_weight": { "type": "integer", "description": "The default weight of the endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 10 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Nacos, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } }, "auth": { "description": "Nacos authentication configuration.", "oneOf": [ { "title": "Username & Password", "properties": { "username": { "description": "The username of the Nacos API.", "type": "string", "minLength": 1, "example": null }, "password": { "description": "The password of the Nacos API.", "type": "string", "minLength": 1, "example": null } }, "required": [ "username", "password" ] }, { "title": "Token", "properties": { "token": { "type": "string", "description": "The token of the Nacos service.", "minLength": 1 } }, "required": [ "token" ] }, { "title": "Access Key & Secret Key", "properties": { "access_key": { "description": "The access key of the Nacos API.", "type": "string", "minLength": 1 }, "secret_key": { "description": "The secret key of the Nacos API.", "type": "string", "minLength": 1 } }, "required": [ "access_key", "secret_key" ] } ] } } } } }, { "title": "Consul", "type": "object", "required": [ "type", "consul_config" ], "properties": { "type": { "type": "string", "enum": [ "consul" ], "description": "The Consul service type." }, "consul_config": { "type": "object", "required": [ "servers" ], "description": "Consul service registry configurations.", "properties": { "servers": { "description": "The addresses of the Consul servers.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 }, "example": [ "http://127.0.0.1:8500" ] }, "token": { "description": "The ACL token for authenticating with Consul.", "type": "string" }, "weight": { "type": "integer", "description": "The default weight of the discovered endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 30 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Consul, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } } } } } } ] } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the service registry connection.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The service registry model.", "allOf": [ { "type": "object", "required": [ "name", "type" ], "allOf": [ { "type": "object", "properties": { "name": { "example": "sample-service-registry", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "description": "Service registry description.", "example": "service registry description" }, "health_check": { "type": "object", "description": "Health check configurations.", "properties": { "probe_interval": { "default": 15, "minimum": 1, "type": "integer", "format": "int32", "description": "The time interval for checking service registry (in seconds)." }, "probe_timeout": { "default": 5, "minimum": 1, "type": "integer", "format": "int32", "description": "The timeout for checking service registry (in seconds)." } } } } }, { "oneOf": [ { "title": "Kubernetes", "type": "object", "required": [ "type", "kubernetes_config" ], "properties": { "type": { "type": "string", "enum": [ "kubernetes" ], "description": "The kubernetes service type." }, "kubernetes_config": { "type": "object", "description": "Kubernetes service registry configurations.", "properties": { "service": { "description": "The IP address of the Kubernetes API server.", "type": "object", "required": [ "schema", "host", "port" ], "properties": { "schema": { "type": "string", "enum": [ "http", "https" ] }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "string", "minLength": 1, "example": "6443" } } }, "namespace_selector": { "description": "The namespace selector to filter target namespaces.", "type": "object", "nullable": true, "properties": { "equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to match namespaces whose name is exactly equal to the specified string.", "example": "prod" }, "not_equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to exclude namespaces whose name is exactly equal to the specified string.", "example": "kube-system" }, "match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to match namespaces whose names match any of the specified strings.", "example": [ "team-a" ] }, "not_match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to exclude namespaces whose names match any of the specified strings.", "example": [ "test-env" ] } }, "oneOf": [ { "title": "Equal", "required": [ "equal" ] }, { "title": "Not Equal", "required": [ "not_equal" ] }, { "title": "Match", "required": [ "match" ] }, { "title": "Not Match", "required": [ "not_match" ] } ] }, "label_selector": { "description": "The label selector to filter target endpoints.", "type": "string", "example": "app=nginx,env=prod" }, "client": { "description": "The client name.", "oneOf": [ { "title": "Token File", "properties": { "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "pattern": "^[^\\:*?\"<>|]*$", "example": "/var/run/secrets/kubernetes.io/serviceaccount/token" } }, "required": [ "token_file" ] }, { "title": "Token Value", "properties": { "token": { "description": "The token of the Kubernetes service account.", "type": "string", "pattern": "^[A-Za-z0-9+\\/._=-]+$" } }, "required": [ "token" ] } ] } } } } }, { "title": "Nacos", "type": "object", "required": [ "type", "nacos_config" ], "properties": { "type": { "type": "string", "enum": [ "nacos" ], "description": "The Nacos service type." }, "nacos_config": { "type": "object", "required": [ "hosts" ], "description": "Nacos service registry configurations.", "properties": { "hosts": { "description": "The address of the Nacos API server.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 } }, "prefix": { "description": "The prefix of the Nacos API.", "type": "string", "default": "/nacos/v1" }, "default_weight": { "type": "integer", "description": "The default weight of the endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 10 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Nacos, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } }, "auth": { "description": "Nacos authentication configuration.", "oneOf": [ { "title": "Username & Password", "properties": { "username": { "description": "The username of the Nacos API.", "type": "string", "minLength": 1, "example": null }, "password": { "description": "The password of the Nacos API.", "type": "string", "minLength": 1, "example": null } }, "required": [ "username", "password" ] }, { "title": "Token", "properties": { "token": { "type": "string", "description": "The token of the Nacos service.", "minLength": 1 } }, "required": [ "token" ] }, { "title": "Access Key & Secret Key", "properties": { "access_key": { "description": "The access key of the Nacos API.", "type": "string", "minLength": 1 }, "secret_key": { "description": "The secret key of the Nacos API.", "type": "string", "minLength": 1 } }, "required": [ "access_key", "secret_key" ] } ] } } } } }, { "title": "Consul", "type": "object", "required": [ "type", "consul_config" ], "properties": { "type": { "type": "string", "enum": [ "consul" ], "description": "The Consul service type." }, "consul_config": { "type": "object", "required": [ "servers" ], "description": "Consul service registry configurations.", "properties": { "servers": { "description": "The addresses of the Consul servers.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 }, "example": [ "http://127.0.0.1:8500" ] }, "token": { "description": "The ACL token for authenticating with Consul.", "type": "string" }, "weight": { "type": "integer", "description": "The default weight of the discovered endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 30 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Consul, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } } } } } } ] } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "lost_connection", "connecting" ], "default": "connecting", "description": "The status of the service registry." }, "last_connect_time": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/instance_token": { "post": { "tags": [ "Gateway Group", "Gateway Instance" ], "summary": "Create a token for all gateway instances in a gateway group", "operationId": "createGatewayInstanceToken", "description": "IAM Action: `gateway:CreateGatewayInstance`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "only_token", "description": "If true, the response will only contain the token.", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Gateway group token created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "The token.", "type": "object", "properties": { "id": { "description": "Token ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "token_plain_text": { "type": "string", "description": "The token in plain text.", "example": "tubqbejxbhuao-2MIFcKD1dfaIm0i36Cqb2V2xfuIdwh9f60PJy0C1wYxBMeoTU2-8d2adba4c1444dd69a6d66e47b5ebff1" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "Get a service registry connection on a gateway group", "operationId": "getServiceRegistry", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved or modified the service registry connection.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "description": "The service registry model.", "allOf": [ { "type": "object", "required": [ "name", "type" ], "allOf": [ { "type": "object", "properties": { "name": { "example": "sample-service-registry", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "description": "Service registry description.", "example": "service registry description" }, "health_check": { "type": "object", "description": "Health check configurations.", "properties": { "probe_interval": { "default": 15, "minimum": 1, "type": "integer", "format": "int32", "description": "The time interval for checking service registry (in seconds)." }, "probe_timeout": { "default": 5, "minimum": 1, "type": "integer", "format": "int32", "description": "The timeout for checking service registry (in seconds)." } } } } }, { "oneOf": [ { "title": "Kubernetes", "type": "object", "required": [ "type", "kubernetes_config" ], "properties": { "type": { "type": "string", "enum": [ "kubernetes" ], "description": "The kubernetes service type." }, "kubernetes_config": { "type": "object", "description": "Kubernetes service registry configurations.", "properties": { "service": { "description": "The IP address of the Kubernetes API server.", "type": "object", "required": [ "schema", "host", "port" ], "properties": { "schema": { "type": "string", "enum": [ "http", "https" ] }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "string", "minLength": 1, "example": "6443" } } }, "namespace_selector": { "description": "The namespace selector to filter target namespaces.", "type": "object", "nullable": true, "properties": { "equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to match namespaces whose name is exactly equal to the specified string.", "example": "prod" }, "not_equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to exclude namespaces whose name is exactly equal to the specified string.", "example": "kube-system" }, "match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to match namespaces whose names match any of the specified strings.", "example": [ "team-a" ] }, "not_match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to exclude namespaces whose names match any of the specified strings.", "example": [ "test-env" ] } }, "oneOf": [ { "title": "Equal", "required": [ "equal" ] }, { "title": "Not Equal", "required": [ "not_equal" ] }, { "title": "Match", "required": [ "match" ] }, { "title": "Not Match", "required": [ "not_match" ] } ] }, "label_selector": { "description": "The label selector to filter target endpoints.", "type": "string", "example": "app=nginx,env=prod" }, "client": { "description": "The client name.", "oneOf": [ { "title": "Token File", "properties": { "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "pattern": "^[^\\:*?\"<>|]*$", "example": "/var/run/secrets/kubernetes.io/serviceaccount/token" } }, "required": [ "token_file" ] }, { "title": "Token Value", "properties": { "token": { "description": "The token of the Kubernetes service account.", "type": "string", "pattern": "^[A-Za-z0-9+\\/._=-]+$" } }, "required": [ "token" ] } ] } } } } }, { "title": "Nacos", "type": "object", "required": [ "type", "nacos_config" ], "properties": { "type": { "type": "string", "enum": [ "nacos" ], "description": "The Nacos service type." }, "nacos_config": { "type": "object", "required": [ "hosts" ], "description": "Nacos service registry configurations.", "properties": { "hosts": { "description": "The address of the Nacos API server.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 } }, "prefix": { "description": "The prefix of the Nacos API.", "type": "string", "default": "/nacos/v1" }, "default_weight": { "type": "integer", "description": "The default weight of the endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 10 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Nacos, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } }, "auth": { "description": "Nacos authentication configuration.", "oneOf": [ { "title": "Username & Password", "properties": { "username": { "description": "The username of the Nacos API.", "type": "string", "minLength": 1, "example": null }, "password": { "description": "The password of the Nacos API.", "type": "string", "minLength": 1, "example": null } }, "required": [ "username", "password" ] }, { "title": "Token", "properties": { "token": { "type": "string", "description": "The token of the Nacos service.", "minLength": 1 } }, "required": [ "token" ] }, { "title": "Access Key & Secret Key", "properties": { "access_key": { "description": "The access key of the Nacos API.", "type": "string", "minLength": 1 }, "secret_key": { "description": "The secret key of the Nacos API.", "type": "string", "minLength": 1 } }, "required": [ "access_key", "secret_key" ] } ] } } } } }, { "title": "Consul", "type": "object", "required": [ "type", "consul_config" ], "properties": { "type": { "type": "string", "enum": [ "consul" ], "description": "The Consul service type." }, "consul_config": { "type": "object", "required": [ "servers" ], "description": "Consul service registry configurations.", "properties": { "servers": { "description": "The addresses of the Consul servers.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 }, "example": [ "http://127.0.0.1:8500" ] }, "token": { "description": "The ACL token for authenticating with Consul.", "type": "string" }, "weight": { "type": "integer", "description": "The default weight of the discovered endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 30 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Consul, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } } } } } } ] } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "lost_connection", "connecting" ], "default": "connecting", "description": "The status of the service registry." }, "last_connect_time": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "Update a service registry connection on a gateway group", "operationId": "putServiceRegistry", "description": "IAM Action: `gateway:UpdateServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type" ], "allOf": [ { "type": "object", "properties": { "name": { "example": "sample-service-registry", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "description": "Service registry description.", "example": "service registry description" }, "health_check": { "type": "object", "description": "Health check configurations.", "properties": { "probe_interval": { "default": 15, "minimum": 1, "type": "integer", "format": "int32", "description": "The time interval for checking service registry (in seconds)." }, "probe_timeout": { "default": 5, "minimum": 1, "type": "integer", "format": "int32", "description": "The timeout for checking service registry (in seconds)." } } } } }, { "oneOf": [ { "title": "Kubernetes", "type": "object", "required": [ "type", "kubernetes_config" ], "properties": { "type": { "type": "string", "enum": [ "kubernetes" ], "description": "The kubernetes service type." }, "kubernetes_config": { "type": "object", "description": "Kubernetes service registry configurations.", "properties": { "service": { "description": "The IP address of the Kubernetes API server.", "type": "object", "required": [ "schema", "host", "port" ], "properties": { "schema": { "type": "string", "enum": [ "http", "https" ] }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "string", "minLength": 1, "example": "6443" } } }, "namespace_selector": { "description": "The namespace selector to filter target namespaces.", "type": "object", "nullable": true, "properties": { "equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to match namespaces whose name is exactly equal to the specified string.", "example": "prod" }, "not_equal": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9_.]*[a-z0-9])?$", "description": "Value to exclude namespaces whose name is exactly equal to the specified string.", "example": "kube-system" }, "match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to match namespaces whose names match any of the specified strings.", "example": [ "team-a" ] }, "not_match": { "type": "array", "items": { "type": "string", "pattern": "^[\\x21-\\x7e]*$" }, "minItems": 1, "description": "List of values to exclude namespaces whose names match any of the specified strings.", "example": [ "test-env" ] } }, "oneOf": [ { "title": "Equal", "required": [ "equal" ] }, { "title": "Not Equal", "required": [ "not_equal" ] }, { "title": "Match", "required": [ "match" ] }, { "title": "Not Match", "required": [ "not_match" ] } ] }, "label_selector": { "description": "The label selector to filter target endpoints.", "type": "string", "example": "app=nginx,env=prod" }, "client": { "description": "The client name.", "oneOf": [ { "title": "Token File", "properties": { "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "pattern": "^[^\\:*?\"<>|]*$", "example": "/var/run/secrets/kubernetes.io/serviceaccount/token" } }, "required": [ "token_file" ] }, { "title": "Token Value", "properties": { "token": { "description": "The token of the Kubernetes service account.", "type": "string", "pattern": "^[A-Za-z0-9+\\/._=-]+$" } }, "required": [ "token" ] } ] } } } } }, { "title": "Nacos", "type": "object", "required": [ "type", "nacos_config" ], "properties": { "type": { "type": "string", "enum": [ "nacos" ], "description": "The Nacos service type." }, "nacos_config": { "type": "object", "required": [ "hosts" ], "description": "Nacos service registry configurations.", "properties": { "hosts": { "description": "The address of the Nacos API server.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 } }, "prefix": { "description": "The prefix of the Nacos API.", "type": "string", "default": "/nacos/v1" }, "default_weight": { "type": "integer", "description": "The default weight of the endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 10 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Nacos, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } }, "auth": { "description": "Nacos authentication configuration.", "oneOf": [ { "title": "Username & Password", "properties": { "username": { "description": "The username of the Nacos API.", "type": "string", "minLength": 1, "example": null }, "password": { "description": "The password of the Nacos API.", "type": "string", "minLength": 1, "example": null } }, "required": [ "username", "password" ] }, { "title": "Token", "properties": { "token": { "type": "string", "description": "The token of the Nacos service.", "minLength": 1 } }, "required": [ "token" ] }, { "title": "Access Key & Secret Key", "properties": { "access_key": { "description": "The access key of the Nacos API.", "type": "string", "minLength": 1 }, "secret_key": { "description": "The secret key of the Nacos API.", "type": "string", "minLength": 1 } }, "required": [ "access_key", "secret_key" ] } ] } } } } }, { "title": "Consul", "type": "object", "required": [ "type", "consul_config" ], "properties": { "type": { "type": "string", "enum": [ "consul" ], "description": "The Consul service type." }, "consul_config": { "type": "object", "required": [ "servers" ], "description": "Consul service registry configurations.", "properties": { "servers": { "description": "The addresses of the Consul servers.", "type": "array", "minItems": 1, "items": { "type": "string", "format": "url", "minLength": 1 }, "example": [ "http://127.0.0.1:8500" ] }, "token": { "description": "The ACL token for authenticating with Consul.", "type": "string" }, "weight": { "type": "integer", "description": "The default weight of the discovered endpoints.", "minimum": 1, "maximum": 100, "example": 100, "default": 100 }, "fetch_interval": { "type": "integer", "description": "The interval for fetching endpoints (in seconds).", "example": 30, "default": 30 }, "timeout": { "type": "object", "description": "Timeout settings for connecting to, sending requests to, and receiving responses from Consul, in seconds.", "properties": { "connect": { "type": "integer", "description": "Connection timeout.", "example": 2, "default": 2 }, "send": { "type": "integer", "description": "Sending timeout in seconds.", "example": 2, "default": 2 }, "read": { "type": "integer", "description": "Reading timeout in seconds.", "example": 5, "default": 5 } } } } } } } ] } ] } } }, "required": true }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "delete": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "Delete a service registry connection on a gateway group", "operationId": "deleteServiceRegistry", "description": "IAM Action: `gateway:DisconnectServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/connected_services": { "get": { "tags": [ "Service Registry", "Gateway Group", "Published Service" ], "summary": "List all published services connected to a service registry", "operationId": "listServiceRegistryConnectedServices", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order published services by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at", "publish_time", "name" ] } }, { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of published services connected to this service registry.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of service versions.", "items": { "allOf": [ { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "unhealthy_nodes_count": { "type": "integer", "description": "Unhealthy nodes count.", "example": 0 }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/kubernetes/internal_services": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "List all internal services in a Kubernetes service registry", "operationId": "listKubernetesInternalServices", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the Kubernetes internal services from the service registry.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "kubernetes" ], "description": "The service type." }, "internal_services": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "description": "An array of internal service names." } }, "description": "A map of internal services. The Key is the name of namespace and value is the array of internal service names.", "example": { "default": [ "service1", "service2" ], "kube-system": [ "kube-dns" ] } } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/nacos/namespaces": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "List all namespaces in a Nacos service registry", "operationId": "listNacosNamespaces", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of Nacos namespaces.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of Nacos namespaces.", "items": { "type": "object", "properties": { "namespace": { "type": "string", "description": "Nacos namespace ID.", "example": "f8b9a1d3-74c7-4a70-9b89-1fc447c1b2e6" }, "namespace_show_name": { "type": "string", "description": "Nacos namespace name.", "example": "public" } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/nacos/namespaces/{nacos_namespace}/groups": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "List all groups in a Nacos namespace", "operationId": "listNacosGroups", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "nacos_namespace", "in": "path", "required": true, "description": "Nacos namespace name.", "example": "public", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of Nacos groups.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of Nacos groups.", "items": { "type": "string" }, "example": [ "DEFAULT_GROUP", "DEV_GROUP", "TEST_GROUP", "STAGING_GROUP", "PROD_GROUP" ] }, "total": { "example": 5 } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/nacos/namespaces/{nacos_namespace}/groups/{nacos_group}/services": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "List all internal services in a Nacos group", "operationId": "listNacosInternalServices", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "nacos_namespace", "in": "path", "required": true, "description": "Nacos namespace name.", "example": "public", "schema": { "minimum": 1, "type": "string" } }, { "name": "nacos_group", "in": "path", "required": true, "description": "Nacos group.", "example": "DEFAULT_GROUP", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of Nacos services.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of Nacos services.", "items": { "type": "string" }, "example": [ "auth-service", "user-service", "order-service", "payment-service", "inventory-service" ] }, "total": { "example": 5 } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/nacos/namespaces/{nacos_namespace}/groups/{nacos_group}/services/{nacos_service}/instances_metadata": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "Get all instance metadata of a Nacos services registry", "operationId": "getNacosInstancesMetadata", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "nacos_namespace", "in": "path", "required": true, "description": "Nacos namespace name.", "example": "public", "schema": { "minimum": 1, "type": "string" } }, { "name": "nacos_group", "in": "path", "required": true, "description": "Nacos group.", "example": "DEFAULT_GROUP", "schema": { "minimum": 1, "type": "string" } }, { "name": "nacos_service", "in": "path", "required": true, "description": "Nacos service.", "example": "api7ee3-keycloak", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the Nacos instance metadata.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "An object of Nacos instance metadata.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "version": [ "1.0.0", "1.0.1" ], "env": [ "prod", "staging" ], "location": [ "beijing", "shanghai" ] } }, "total": { "type": "integer", "example": 3 }, "list": { "type": "array", "description": "Raw list of metadata for each instance.", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "example": [ { "version": "1.0.0", "env": "prod", "location": "beijing" }, { "version": "1.0.1", "env": "prod", "location": "shanghai" }, { "version": "1.0.0", "env": "staging", "location": "beijing" } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/consul/datacenters": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "List all datacenters in a Consul service registry", "operationId": "listConsulDatacenters", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of Consul datacenters.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of Consul datacenters.", "items": { "type": "string" }, "example": [ "dc1", "dc2" ] }, "total": { "example": 2 } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/consul/datacenters/{consul_datacenter}/services": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "List all services in a Consul datacenter", "operationId": "listConsulServices", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "consul_datacenter", "in": "path", "required": true, "description": "Consul datacenter name.", "example": "dc1", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of Consul services.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of Consul services.", "items": { "type": "string" }, "example": [ "web", "api", "consul" ] }, "total": { "example": 3 } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/consul/datacenters/{consul_datacenter}/services/{consul_service}/instances_metadata": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "Get all instance metadata of a Consul service", "operationId": "getConsulServiceInstancesMetadata", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "consul_datacenter", "in": "path", "required": true, "description": "Consul datacenter name.", "example": "dc1", "schema": { "minimum": 1, "type": "string" } }, { "name": "consul_service", "in": "path", "required": true, "description": "Consul service name.", "example": "web", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the Consul service instance metadata.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "An object of Consul service instance metadata.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "version": [ "1.0.0", "1.0.1" ], "env": [ "prod", "staging" ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/gateway_groups/{gateway_group_id}/service_registries/{service_registry_id}/health_check_history": { "get": { "tags": [ "Service Registry", "Gateway Group" ], "summary": "Get health check history of a service registry connection on a gateway group", "operationId": "getServiceRegistryHealthCheckHistory", "description": "IAM Action: `gateway:GetServiceRegistry`, Resource: `arn:api7:gateway:gatewaygroup/%s`", "parameters": [ { "name": "service_registry_id", "in": "path", "required": true, "description": "Service registry ID.", "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "schema": { "minimum": 1, "type": "string" } }, { "name": "gateway_group_id", "in": "path", "required": true, "example": "86fb9981-d9d2-4555-9df8-91ae92129335", "description": "Gateway group ID.", "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order health check history by.", "schema": { "type": "string", "default": "connect_time", "enum": [ "connect_time" ] } }, { "name": "status", "in": "query", "description": "Service registry connection status.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "healthy", "lost_connection", "connecting" ] } } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the health check history for the service registry.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of health check results of the service registry.", "items": { "allOf": [ { "type": "object", "properties": { "instance_id": { "description": "Instance ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_registry_id": { "description": "Service registry ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "hostname": { "type": "string", "description": "Service registry hostname.", "example": "nacos-srv.test" }, "status": { "type": "string", "enum": [ "healthy", "lost_connection", "connecting" ] }, "connect_time": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/service_versions/{service_version_id}/oas": { "get": { "tags": [ "Service Template" ], "summary": "Get the OpenAPI Specification of a service version", "operationId": "getServiceVersionOAS", "description": "Retrieve the OpenAPI 3.0 document generated from a specific service version snapshot. Use this for documentation export, change review, or rollback planning.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_version_id", "description": "The unique identifier of the service version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the OpenAPI specification for the service.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "raw_openapi": { "type": "string", "description": "The raw OpenAPI spec of the service.", "example": "Raw OpenAPI spec" }, "api_count": { "type": "integer", "description": "The number of APIs in the service.", "example": 10 }, "api_desc": { "type": "string", "description": "The description of the OAS.", "example": "OAS description." } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/service_versions/{service_version_id}": { "get": { "tags": [ "Service Template" ], "summary": "Get a service version", "operationId": "getServiceVersion", "description": "Retrieve a specific historical service version snapshot by ID. Service version IDs can be discovered by listing versions for the service template.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_version_id", "description": "The unique identifier of the service version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/service_versions/{service_version_id}/routes": { "get": { "tags": [ "Service Template" ], "summary": "Get all routes in a service version", "operationId": "listRoutesInServiceVersion", "description": "List HTTP route snapshots contained in the specified service version. This helps compare historical routing configuration or inspect rollback candidates.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_version_id", "description": "The unique identifier of the service version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of routes in the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of route versions.", "items": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/service_versions/{service_version_id}/routes/{route_version_id}": { "get": { "tags": [ "Service Template" ], "summary": "Get a route in a service version", "operationId": "getRouteInServiceVersion", "description": "Retrieve a specific HTTP route snapshot from a service version. Use this endpoint for detailed route-level audits of historical service states.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_version_id", "description": "The unique identifier of the service version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "route_version_id", "description": "The unique identifier of the route version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the route from the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/service_versions/{service_version_id}/stream_routes": { "get": { "tags": [ "Service Template" ], "summary": "Get all stream routes in a service versions", "operationId": "listStreamRoutesInServiceVersion", "description": "List stream route snapshots included in the specified service version. This is useful when auditing TCP/UDP traffic configuration history.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_version_id", "description": "The unique identifier of the service version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of stream routes in the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of route versions.", "items": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "stream_route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/service_versions/{service_version_id}/stream_routes/{stream_route_version_id}": { "get": { "tags": [ "Service Template" ], "summary": "Get a stream route in a service version", "operationId": "getStreamRouteInServiceVersion", "description": "Retrieve a specific stream route snapshot from a service version for deep inspection or historical troubleshooting.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_version_id", "description": "The unique identifier of the service version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "stream_route_version_id", "description": "The unique identifier of the stream route version.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the stream route from the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "remote_addr": { "description": "Client address filter. If the client request does not originate from `remote_addr`, the request will not be forwarded to the stream server.", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, "server_addr": { "type": "string", "description": "Stream server address.", "anyOf": [ { "title": "IPAddress", "type": "string", "anyOf": [ { "title": "IPv4", "type": "string", "example": "127.0.0.1" }, { "title": "IPv4/CIDR", "type": "string", "example": "127.0.0.1/24" }, { "title": "IPv6", "type": "string", "example": "2001:db8::" }, { "title": "IPv6/CIDR", "type": "string", "example": "2001:db8::/32" } ] }, { "type": "string", "title": "Domain" } ], "example": "mysql" }, "server_port": { "type": "integer", "maximum": 65535, "description": "Stream server port.", "example": 3306 } } }, { "type": "object", "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "ip-restriction": { "whitelist": [ "192.168.0.1/24" ], "message": "Access denied" } } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "stream_route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_version_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/services/publish": { "post": { "tags": [ "Service Template" ], "summary": "Publish a service template to a gateway group", "operationId": "publishServiceTemplate", "description": "IAM Action: `gateway:PublishServices`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "create_new_version": { "type": "boolean", "description": "If true, create a new service version." }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "services": { "type": "array", "minItems": 1, "description": "Services configurations.", "items": { "type": "object", "required": [ "service_id", "version" ], "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "description": "Service version.", "type": "string" }, "service_version_id": { "description": "Required when `create_new_version` is set to `false`.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } } } } } }, "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/services/conflict_check": { "post": { "tags": [ "Published Service" ], "summary": "Check service conflict", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "create_new_version": { "type": "boolean", "description": "If true, create a new service version." }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "services": { "type": "array", "minItems": 1, "description": "Services configurations.", "items": { "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "hosts": { "type": "array", "description": "The hosts of the service to accept incoming requests.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "path_prefix": { "maxLength": 4096, "minLength": 1, "pattern": "^/", "type": "string", "description": "The listening path prefix of the service.", "example": "/test" } } }, { "type": "object", "required": [ "service_id" ], "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version." }, "service_version_id": { "description": "Required when `create_new_version` is set to `false`.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "status": { "default": 1, "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "routes": { "type": "array", "items": { "description": "The route with management fields.", "allOf": [ { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" } } } ] } } } } ] } } } } } } }, "responses": { "200": { "description": "Successfully completed the route conflict check. Returns duplicate and overlapping routes if any.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "duplicate": { "type": "array", "description": "An array of duplicated services and routes.", "items": { "type": "array", "description": "An array of conflicting services and routes.", "items": { "type": "object", "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "type": "string", "description": "Service name.", "example": "httpbin-svc" }, "route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_name": { "type": "string", "description": "Route name.", "example": "httpbin-route" }, "url": { "type": "string", "description": "Route URL.", "example": "/test" } } } } }, "overlapping": { "type": "array", "description": "An array of overlapping services and routes.", "items": { "type": "array", "description": "An array of conflicting services and routes.", "items": { "type": "object", "properties": { "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "service_name": { "type": "string", "description": "Service name.", "example": "httpbin-svc" }, "route_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "route_name": { "type": "string", "description": "Route name.", "example": "httpbin-route" }, "url": { "type": "string", "description": "Route URL.", "example": "/test" } } } } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/services/{service_template_id}/published_services": { "get": { "tags": [ "Service Template" ], "summary": "List all published version of a service template on multiple gateway groups", "operationId": "listServiceTemplatePublishedVersions", "description": "IAM Action: `gateway:GetPublishedService`, Resource: `arn:api7:gateway:gatewaygroup/%s/publishedservice/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of published services.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of published services.", "items": { "allOf": [ { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] }, { "type": "object", "properties": { "gateway_group_name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "unhealthy_nodes_count": { "type": "integer", "description": "Unhealthy nodes count.", "example": 0 }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/services/{service_template_id}/versions/{version}": { "get": { "tags": [ "Service Template" ], "summary": "Get the service version name", "operationId": "getServiceVersionByVersionName", "description": "Retrieve a service version snapshot by template ID and semantic version name. Use this when version labels are known but internal version IDs are not.\n\n**Required IAM Permission:** Action `gateway:GetServiceTemplate`, Resource `arn:api7:gateway:servicetemplate/%s`", "parameters": [ { "name": "service_template_id", "description": "The unique identifier of the service template.", "in": "path", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "version", "description": "Service version.", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the service version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "minProperties": 1, "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" } } } ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "apisix_service_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "service_id": { "description": "The service ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "version": { "type": "string", "description": "Service version.", "example": "1.3.2" }, "created_at": { "description": "The time (first release) when a service version is created.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The time when a service version is updated.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/plugins": { "get": { "tags": [ "Plugin" ], "summary": "Get all plugin details", "operationId": "getPlugin", "parameters": [ { "name": "subsystem", "in": "query", "schema": { "type": "string", "default": "http", "enum": [ "http", "stream" ], "example": "stream" }, "description": "Type to filter the plugin list. `http` will only show L7 plugins and `stream` will only show L4 plugins." }, { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of plugins.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "array", "items": { "type": "object", "properties": { "plugin_name": { "description": "Name of the plugin.", "example": "prometheus", "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "description": "Catalog of the plugin. Plugins are categorized into Authentication, Security, AI, Traffic, Transformation, Observability, Serverless, General, and Other Protocols.", "example": "Observability" }, "is_custom": { "type": "boolean", "description": "If true, the plugin is a custom plugin.", "example": false } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/plugins/catalogs": { "get": { "tags": [ "Plugin" ], "summary": "List all plugin catalogs", "operationId": "listPluginCatalogs", "responses": { "200": { "description": "Successfully retrieved the list of plugin catalog categories.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "array", "items": { "type": "string" }, "example": [ "General", "Traffic", "Observability", "Serverless", "Security", "Transformation", "Authentication", "Other protocols" ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/plugins/{plugin_name}/usage": { "get": { "tags": [ "Plugin" ], "summary": "Get the usage of a plugin in all gateway groups", "operationId": "getPluginUsage", "parameters": [ { "name": "plugin_name", "description": "Name of the plugin.", "in": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": true } ], "responses": { "200": { "description": "Successfully retrieved the plugin usage across published services, consumers, and global rules.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "example": { "consumer_credential": { "list": [ { "name": "ka", "id": "9f1c2c80b6093aa7e9cbd9f0855f56586a646ba0", "gateway_group_id": "default", "gateway_group_name": "default" }, { "name": "jack", "id": "439129f8-a6c5-4ea7-9f96-6ed108cfc0b0", "gateway_group_id": "ce9bf912-eb47-4c28-85a7-ffae5256d226", "gateway_group_name": "jack" }, { "name": "test", "id": "21c3b211-2463-4cfc-8eb4-1f8cd679eec0", "gateway_group_id": "b14f4ec3-f79b-4aa7-baeb-f892540c26f3", "gateway_group_name": "29jjc" } ], "total": 3 }, "published_service": { "list": [ { "name": "httpbin", "id": "60109630-3022-4c6d-9b1f-0440ec88ef5f", "gateway_group_id": "bfc91d42-b83a-4309-8cab-6763c27f715e", "gateway_group_name": "jw_test" }, { "name": "name2", "id": "4bc1938e-8d3c-4a89-8089-b31bfa6989dc", "gateway_group_id": "b14f4ec3-f79b-4aa7-baeb-f892540c26f3", "gateway_group_name": "29jjc" } ], "total": 2 } }, "properties": { "published_service": { "type": "object", "description": "Published services in all gateway groups.", "properties": { "total": { "type": "integer", "description": "Total number of published services." }, "list": { "type": "array", "description": "An array of published services in all gateway groups.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } } } } }, "consumer": { "type": "object", "description": "Consumers in all gateway groups.", "properties": { "total": { "type": "integer", "description": "Total number of consumers." }, "list": { "type": "array", "description": "An array of consumers in all gateway groups.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } } } } }, "global_rule": { "type": "object", "description": "Global rules in all gateway groups.", "properties": { "total": { "type": "integer", "description": "Total number of global rules." }, "list": { "type": "array", "description": "An array of global rules in all gateway groups.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "gateway_group_id": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" }, "gateway_group_name": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } } } } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/openapi/request_body_schema": { "get": { "tags": [ "Schema" ], "summary": "Get OpenAPI schema", "description": "The endpoint returns the request body schema of PUT/POST requests for users to understand how to structure a request.", "operationId": "getOpenAPISchema", "parameters": [ { "name": "method", "description": "HTTP method to determine which request body to return.", "in": "query", "required": true, "schema": { "minimum": 1, "type": "string", "enum": [ "POST", "PUT" ] } }, { "name": "path", "description": "API endpoint.", "in": "query", "required": true, "example": "/apisix/admin/consumers", "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the request body schema for the specified resource.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "example": { "description": "The consumer description.", "properties": { "desc": { "description": "The object description.", "maxLength": 65536, "type": "string" }, "labels": { "additionalProperties": { "maxLength": 65536, "minLength": 1, "pattern": "^.+$", "type": "string" }, "example": { "keyA": "valueA", "keyB": "valueB" }, "type": "object" }, "plugins": { "description": "The key-value pairs which represent the plugins attached on the object.", "type": "object" }, "username": { "maxLength": 512, "minLength": 1, "pattern": "^[a-zA-Z0-9_\\-]+$", "type": "string" } }, "required": [ "username" ], "type": "object" } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/schema/core": { "get": { "tags": [ "Schema" ], "summary": "Get core resources schema", "operationId": "getCoreAPISchema", "description": "Retrieve schema definitions for core gateway resources. Use these schemas to validate payload structures and build configuration tooling.", "responses": { "200": { "description": "Successfully retrieved the core APISIX resource schemas.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "service": { "type": "object", "description": "Service(L7) schema." }, "route": { "type": "object", "description": "Route(L7) schema." }, "stream_service": { "type": "object", "description": "Stream service(L4) schema." }, "stream_route": { "type": "object", "description": "Stream route(L4) schema." }, "upstream": { "type": "object", "description": "Upstream schema." }, "consumer": { "type": "object", "description": "Consumer schema." }, "consumer_credential": { "type": "object", "description": "Consumer credential schema." }, "global_rule": { "type": "object", "description": "Global rule schema." }, "ssl": { "type": "object", "description": "SSL schema." }, "aws_secret": { "type": "object", "description": "AWS secret schema." }, "vault_secret": { "type": "object", "description": "Vault secret schema." }, "kubernetes_secret": { "type": "object", "description": "Kubernetes secret schema." }, "plugin_metadata": { "type": "object", "description": "Plugin metadata schema." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/labels/{resource_type}": { "get": { "tags": [ "Label" ], "summary": "Get all labels of a resource type", "operationId": "listLabels", "description": "List available key-value labels for the specified resource type. Use these labels to organize resources and apply label-based filtering in list queries.", "parameters": [ { "name": "resource_type", "in": "path", "required": true, "description": "Resource type.", "schema": { "type": "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" ] } }, { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved all labels across resources.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "k8s/namespace": [ "api7-ingress-system", "default", "api7" ], "manager-by": [ "api7-ingress-controller", "apisix-ingress-controller" ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/system_settings": { "put": { "tags": [ "System Settings" ], "summary": "Update deployment settings", "operationId": "putDeploymentSettings", "description": "Update global system settings that control dashboard deployment behavior and platform-wide defaults. This operation affects configuration used across managed gateway resources.\n\n**Required IAM Permission:** Action `gateway:UpdateDeploymentSetting`, Resource `arn:api7:gateway:gatewaysetting/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dp_manager_address": { "description": "DP manager address.", "maxItems": 32, "minItems": 0, "uniqueItems": true, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "[^\\/]$", "format": "url_scheme_port", "description": "The IP address of the control plane.", "example": "https://192.168.101.10:7943" } }, "source": { "type": "string", "enum": [ "database", "config" ], "description": "The source of the control plane address and Admin API address." }, "admin_api_address": { "type": "string", "format": "url_scheme", "description": "The URL address of the Admin API.", "example": "https://192.168.101.10:7443" }, "file_server_address": { "type": "string", "format": "url_scheme", "description": "The URL address of the file server for serving uploaded files.", "example": "http://192.168.101.10:8080" } } } } } }, "responses": { "200": { "description": "Successfully retrieved or updated the system settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "dp_manager_address": { "description": "DP manager address.", "maxItems": 32, "minItems": 0, "uniqueItems": true, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "[^\\/]$", "format": "url_scheme_port", "description": "The IP address of the control plane.", "example": "https://192.168.101.10:7943" } }, "source": { "type": "string", "enum": [ "database", "config" ], "description": "The source of the control plane address and Admin API address." }, "admin_api_address": { "type": "string", "format": "url_scheme", "description": "The URL address of the Admin API.", "example": "https://192.168.101.10:7443" }, "file_server_address": { "type": "string", "format": "url_scheme", "description": "The URL address of the file server for serving uploaded files.", "example": "http://192.168.101.10:8080" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "System Settings" ], "summary": "Get deployment settings", "operationId": "getDeploymentSettings", "description": "Retrieve current global deployment settings for the control plane. Use this endpoint to inspect active system-level configuration before making changes.", "responses": { "200": { "description": "Successfully retrieved or updated the system settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "dp_manager_address": { "description": "DP manager address.", "maxItems": 32, "minItems": 0, "uniqueItems": true, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "[^\\/]$", "format": "url_scheme_port", "description": "The IP address of the control plane.", "example": "https://192.168.101.10:7943" } }, "source": { "type": "string", "enum": [ "database", "config" ], "description": "The source of the control plane address and Admin API address." }, "admin_api_address": { "type": "string", "format": "url_scheme", "description": "The URL address of the Admin API.", "example": "https://192.168.101.10:7443" }, "file_server_address": { "type": "string", "format": "url_scheme", "description": "The URL address of the file server for serving uploaded files.", "example": "http://192.168.101.10:8080" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/system_settings/scim": { "put": { "tags": [ "System Settings" ], "summary": "Update SCIM settings", "operationId": "putSCIMSettings", "description": "Update SCIM provisioning settings used for automated identity and user lifecycle synchronization. Changes here affect how external identity providers integrate with organization users.\n\n**Required IAM Permission:** Action `iam:UpdateSCIMProvisioning`, Resource `arn:api7:iam:organization/*`", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "additionalProperties": false, "properties": { "enable_scim": { "type": "boolean", "description": "Enable or disable the SCIM endpoint for provisioning and user management." } } } ] } } } }, "responses": { "200": { "description": "Successfully retrieved the SCIM provisioning settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "additionalProperties": false, "properties": { "enable_scim": { "type": "boolean", "description": "Enable or disable the SCIM endpoint for provisioning and user management." } } }, { "type": "object", "additionalProperties": false, "properties": { "scim_encrypt_key": { "type": "string", "description": "Base64-encoded encryption key used to secure sensitive SCIM data.", "example": "F6OqjCmoRBqFBQIEsdpl33vgfLYTWJe6ynkwitqmaVE=" }, "scim_key_salt": { "type": "string", "description": "Salt value used with the encryption key to strengthen data protection.", "example": "rIXtKGq4oXkzbwEzhzQ3FOa1nOPa2GuPDjdGGJ5TstpCv5irk8KSguBF4YukQqix" } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "System Settings" ], "summary": "Get SCIM settings", "operationId": "getSCIMSettings", "description": "Retrieve the current SCIM provisioning configuration for the organization. Use this to validate synchronization endpoints and provisioning status.\n\n**Required IAM Permission:** Action `iam:GetSCIMProvisioning`, Resource `arn:api7:iam:organization/*`", "responses": { "200": { "description": "Successfully retrieved the SCIM provisioning settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "type": "object", "additionalProperties": false, "properties": { "enable_scim": { "type": "boolean", "description": "Enable or disable the SCIM endpoint for provisioning and user management." } } }, { "type": "object", "additionalProperties": false, "properties": { "scim_encrypt_key": { "type": "string", "description": "Base64-encoded encryption key used to secure sensitive SCIM data.", "example": "F6OqjCmoRBqFBQIEsdpl33vgfLYTWJe6ynkwitqmaVE=" }, "scim_key_salt": { "type": "string", "description": "Salt value used with the encryption key to strengthen data protection.", "example": "rIXtKGq4oXkzbwEzhzQ3FOa1nOPa2GuPDjdGGJ5TstpCv5irk8KSguBF4YukQqix" } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/system_settings/scim/token": { "put": { "tags": [ "System Settings" ], "summary": "Generate SCIM Token", "operationId": "generateSCIMToken", "description": "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.\n\n**Required IAM Permission:** Action `iam:UpdateSCIMProvisioning`, Resource `arn:api7:iam:organization/*`", "responses": { "200": { "description": "Successfully generated a new SCIM authentication token.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "string", "description": "Value of the SCIM token.", "example": "a7scim-t1dJGY89gg8tqMwV2QunhV7472Z26C9VjE3mkZUfgIEpj0WJ1I7FGoEXG92SMYpEw9iciDB2gQI-default" } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/system_settings/smtp_server": { "put": { "tags": [ "System Settings" ], "summary": "Update SMTP server settings", "description": "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.\n\n**Required IAM Permission:** Action `iam:UpdateSMTPServer`, Resource `arn:api7:iam:organization/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "Enable SMTP Server." }, "address": { "type": "string", "format": "host_port", "description": "The SMTP server address in host:port format.", "example": "smtp.example.com:587" }, "authentication_type": { "type": "string", "description": "The authentication type of the SMTP server.", "enum": [ "TLS", "STARTTLS" ] }, "ssl_verify": { "type": "boolean", "description": "Whether to validate server-side SSL." }, "username": { "type": "string", "description": "Username used to authenticate with the SMTP server.", "example": "smtp-user@example.com" }, "password": { "type": "string", "description": "Password used to authenticate with the SMTP server.", "example": "secretpassword123" }, "from_name": { "description": "Sender's name.", "type": "string", "pattern": "^\\s*(\"(?:[^\"\\\\]|\\\\.)*\"|([^<>@]+))?\\s*$", "example": "John Doe" }, "from_address": { "type": "string", "format": "email", "description": "Sender's email address.", "example": "sender@example.com" } }, "required": [ "enable", "address", "ssl_verify", "username", "password", "from_name", "from_address" ] } } } }, "responses": { "200": { "description": "SMTP server settings updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "Enable SMTP Server." }, "address": { "type": "string", "format": "host_port", "description": "The SMTP server address in host:port format.", "example": "smtp.example.com:587" }, "authentication_type": { "type": "string", "description": "The authentication type of the SMTP server.", "enum": [ "TLS", "STARTTLS" ] }, "ssl_verify": { "type": "boolean", "description": "Whether to validate server-side SSL." }, "username": { "type": "string", "description": "Username used to authenticate with the SMTP server.", "example": "smtp-user@example.com" }, "password": { "type": "string", "description": "Password used to authenticate with the SMTP server.", "example": "secretpassword123" }, "from_name": { "description": "Sender's name.", "type": "string", "pattern": "^\\s*(\"(?:[^\"\\\\]|\\\\.)*\"|([^<>@]+))?\\s*$", "example": "John Doe" }, "from_address": { "type": "string", "format": "email", "description": "Sender's email address.", "example": "sender@example.com" } }, "required": [ "enable", "address", "ssl_verify", "username", "password", "from_name", "from_address" ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "System Settings" ], "summary": "Get SMTP server settings", "description": "Retrieve the current SMTP server settings configured for outbound email delivery. Use this endpoint when auditing email configuration or debugging mail issues.\n\n**Required IAM Permission:** Action `iam:GetSMTPServer`, Resource `arn:api7:iam:organization/*`", "responses": { "200": { "description": "Successfully retrieved the SMTP server settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "Enable SMTP Server." }, "address": { "type": "string", "format": "host_port", "description": "The SMTP server address in host:port format.", "example": "smtp.example.com:587" }, "authentication_type": { "type": "string", "description": "The authentication type of the SMTP server.", "enum": [ "TLS", "STARTTLS" ] }, "ssl_verify": { "type": "boolean", "description": "Whether to validate server-side SSL." }, "username": { "type": "string", "description": "Username used to authenticate with the SMTP server.", "example": "smtp-user@example.com" }, "password": { "type": "string", "description": "Password used to authenticate with the SMTP server.", "example": "secretpassword123" }, "from_name": { "description": "Sender's name.", "type": "string", "pattern": "^\\s*(\"(?:[^\"\\\\]|\\\\.)*\"|([^<>@]+))?\\s*$", "example": "John Doe" }, "from_address": { "type": "string", "format": "email", "description": "Sender's email address.", "example": "sender@example.com" } }, "required": [ "enable", "address", "ssl_verify", "username", "password", "from_name", "from_address" ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/system_settings/smtp_server_status": { "get": { "tags": [ "System Settings" ], "summary": "Get SMTP server settings status", "description": "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.", "responses": { "200": { "description": "Successfully retrieved the SMTP server connection status.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "Enable SMTP Server." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/system_settings/login_failure_restriction": { "put": { "tags": [ "System Settings" ], "summary": "Update login failure restriction settings", "description": "Update the policy that temporarily bans built-in users after too many consecutive failed login attempts, including the failure threshold and ban duration.\n\n**Required IAM Permission:** Action `iam:UpdateLoginFailureRestriction`, Resource `arn:api7:iam:organization/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "enable": { "type": "boolean", "description": "Enable temporarily banning built-in users after too many consecutive failed login attempts." }, "failure_threshold": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of consecutive failed login attempts that triggers a temporary login ban.", "example": 5 }, "ban_duration_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "How long, in minutes, a triggered login ban lasts.", "example": 15 } }, "required": [ "enable", "failure_threshold", "ban_duration_minutes" ] } } } }, "responses": { "200": { "description": "Successfully retrieved or updated the login failure restriction settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "enable": { "type": "boolean", "description": "Enable temporarily banning built-in users after too many consecutive failed login attempts." }, "failure_threshold": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of consecutive failed login attempts that triggers a temporary login ban.", "example": 5 }, "ban_duration_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "How long, in minutes, a triggered login ban lasts.", "example": 15 } }, "required": [ "enable", "failure_threshold", "ban_duration_minutes" ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "System Settings" ], "summary": "Get login failure restriction settings", "description": "Retrieve the current policy for temporarily banning built-in users after too many consecutive failed login attempts.\n\n**Required IAM Permission:** Action `iam:GetLoginFailureRestriction`, Resource `arn:api7:iam:organization/*`", "responses": { "200": { "description": "Successfully retrieved or updated the login failure restriction settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "enable": { "type": "boolean", "description": "Enable temporarily banning built-in users after too many consecutive failed login attempts." }, "failure_threshold": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of consecutive failed login attempts that triggers a temporary login ban.", "example": 5 }, "ban_duration_minutes": { "type": "integer", "minimum": 1, "maximum": 1440, "description": "How long, in minutes, a triggered login ban lasts.", "example": 15 } }, "required": [ "enable", "failure_threshold", "ban_duration_minutes" ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/system_infos": { "get": { "tags": [ "System Infos" ], "summary": "Get all system infos", "description": "Retrieve system metadata for the dashboard environment, such as version details, license state, and runtime information used for administration and diagnostics.", "responses": { "200": { "description": "Successfully retrieved the system information.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "api7_ee_version": { "type": "string", "description": "API7 Enterprise version.", "example": "v3.8.10" }, "deployment_id": { "type": "string", "description": "A unique identifier that is automatically generated with each deployment of API7 Enterprise.", "example": "d1e1ea2b-2cff-4c38-b57e-408e1dffec52" }, "deployed_at": { "description": "Timestamp indicating when the API7 EE dashboard was deployed.", "type": "integer", "minimum": 0, "example": 1742288230 }, "free_trial_expired_at": { "description": "Free trial expiry time.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/portal/system_settings/public_access": { "put": { "tags": [ "Developer Portal Settings" ], "summary": "Update developer portal public access", "operationId": "putDeveloperPortalPublicAccess", "description": "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.\n\n**Required IAM Permission:** Action `portal:UpdateDeveloperPortalPublicAccess`, Resource `arn:api7:portal:portal/%s/loginsetting/*`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "portal_public_access": { "type": "boolean", "description": "If true, allow public access to the developer portal." } } } } } }, "responses": { "200": { "description": "Successfully retrieved or updated the developer portal settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "portal_public_access": { "type": "boolean", "description": "If true, allow public access to the developer portal." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Developer Portal Settings" ], "summary": "Get developer portal public access", "operationId": "getDeveloperPortalPublicAccess", "description": "Get the current developer portal public access configuration for the specified portal. Use this to verify login and public accessibility settings.\n\n**Required IAM Permission:** Action `portal:GetDeveloperPortalPublicAccess`, Resource `arn:api7:portal:portal/%s/loginsetting/*`", "parameters": [ { "name": "portal_id", "description": "The unique identifier of the portal instance.", "in": "query", "required": false, "schema": { "default": "default", "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved or updated the developer portal settings.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": false, "properties": { "portal_public_access": { "type": "boolean", "description": "If true, allow public access to the developer portal." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/login_options/{login_option_id}": { "get": { "tags": [ "Dashboard Login Option" ], "summary": "Get a login option", "operationId": "getLoginOption", "description": "Get a login option configuration by ID. This returns settings for one external authentication integration such as OIDC, LDAP, SAML 2.0, or CAS.\n**Required IAM Permission:** Action `iam:GetLoginOption`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "responses": { "200": { "description": "Successfully retrieved or modified the login option.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of boundary mappings defining operations and conditions under which boundaries are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "callback_url": { "type": "string", "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "description": "The logout URL of the OIDC provider.", "example": "https://accounts.example.com/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "description": "The SP root URL of the SAML provider." }, "sp_acs_url": { "type": "string", "description": "The SP ACS URL of the SAML provider." }, "sp_slo_url": { "type": "string", "description": "The SP SLO URL of the SAML provider." }, "sp_metadata_url": { "type": "string", "description": "The SP metadata URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "Dashboard Login Option" ], "summary": "Update a login option", "operationId": "putLoginOption", "description": "Fully update a login option configuration with a complete protocol-specific payload.\n**Required IAM Permission:** Action `iam:UpdateLoginOption`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of permission boundary mappings defining operations and conditions under which permission boundary are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "client_secret", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "root_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The logout URL of the OIDC provider.", "example": "http://api7ee3-keycloak/realms/master/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The SP root URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider.", "default": true }, "logout_idp_session": { "type": "boolean", "description": "Whether redirect to IdP for logout or not.", "default": false }, "private_key": { "type": "string", "description": "The private key of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "CAS", "properties": { "provider_type": { "type": "string", "enum": [ "cas" ], "description": "The login option type." }, "cas_config": { "type": "object", "description": "CAS configuration.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "minLength": 1, "description": "The URL of the CAS provider." }, "send_service": { "type": "boolean", "description": "Whether to send service parameters.", "default": true }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the CAS provider.", "default": true }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the login option.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of boundary mappings defining operations and conditions under which boundaries are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "callback_url": { "type": "string", "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "description": "The logout URL of the OIDC provider.", "example": "https://accounts.example.com/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "description": "The SP root URL of the SAML provider." }, "sp_acs_url": { "type": "string", "description": "The SP ACS URL of the SAML provider." }, "sp_slo_url": { "type": "string", "description": "The SP SLO URL of the SAML provider." }, "sp_metadata_url": { "type": "string", "description": "The SP metadata URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "patch": { "tags": [ "Dashboard Login Option" ], "summary": "Patch a login option", "operationId": "patchLoginOption", "description": "Partially update a login option using JSON Patch (RFC 6902). Use this for targeted changes without replacing full configuration.\n**Required IAM Permission:** Action `iam:UpdateLoginOption`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the login option.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of boundary mappings defining operations and conditions under which boundaries are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "callback_url": { "type": "string", "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "description": "The logout URL of the OIDC provider.", "example": "https://accounts.example.com/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "description": "The SP root URL of the SAML provider." }, "sp_acs_url": { "type": "string", "description": "The SP ACS URL of the SAML provider." }, "sp_slo_url": { "type": "string", "description": "The SP SLO URL of the SAML provider." }, "sp_metadata_url": { "type": "string", "description": "The SP metadata URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "delete": { "tags": [ "Dashboard Login Option" ], "summary": "Delete a login option", "operationId": "deleteLoginOption", "description": "Delete a login option and remove that authentication method from available sign-in choices.\n**Required IAM Permission:** Action `iam:DeleteLoginOption`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/login_options": { "get": { "tags": [ "Dashboard Login Option" ], "summary": "List all login options", "operationId": "listLoginOptions", "description": "List all configured login options for the organization, including protocol-specific provider settings.\n**Required IAM Permission:** Action `iam:GetLoginOption`, Resource `arn:api7:iam:organization/*`", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "Name of the resource." } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of login options.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "Array of login options", "items": { "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of boundary mappings defining operations and conditions under which boundaries are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "callback_url": { "type": "string", "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "description": "The logout URL of the OIDC provider.", "example": "https://accounts.example.com/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "description": "The SP root URL of the SAML provider." }, "sp_acs_url": { "type": "string", "description": "The SP ACS URL of the SAML provider." }, "sp_slo_url": { "type": "string", "description": "The SP SLO URL of the SAML provider." }, "sp_metadata_url": { "type": "string", "description": "The SP metadata URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "post": { "tags": [ "Dashboard Login Option" ], "summary": "Create a login option", "operationId": "createLoginOption", "description": "Create a new login option for external authentication integration. Supported protocols include OIDC, LDAP, SAML 2.0, and CAS.\n**Required IAM Permission:** Action `iam:CreateLoginOption`, Resource `arn:api7:iam:organization/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of permission boundary mappings defining operations and conditions under which permission boundary are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "client_secret", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "root_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The logout URL of the OIDC provider.", "example": "http://api7ee3-keycloak/realms/master/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "oneOf": [ { "format": "url", "minLength": 1, "title": "url" }, { "title": "$env://", "type": "string", "pattern": "^\\$env://", "example": "$env://john-key-auth" } ], "description": "The SP root URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider.", "default": true }, "logout_idp_session": { "type": "boolean", "description": "Whether redirect to IdP for logout or not.", "default": false }, "private_key": { "type": "string", "description": "The private key of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "CAS", "properties": { "provider_type": { "type": "string", "enum": [ "cas" ], "description": "The login option type." }, "cas_config": { "type": "object", "description": "CAS configuration.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "url", "minLength": 1, "description": "The URL of the CAS provider." }, "send_service": { "type": "boolean", "description": "Whether to send service parameters.", "default": true }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the CAS provider.", "default": true }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } }, "responses": { "200": { "description": "Successfully retrieved the paginated list of login options.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "Array of login options", "items": { "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of boundary mappings defining operations and conditions under which boundaries are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "callback_url": { "type": "string", "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "description": "The logout URL of the OIDC provider.", "example": "https://accounts.example.com/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "description": "The SP root URL of the SAML provider." }, "sp_acs_url": { "type": "string", "description": "The SP ACS URL of the SAML provider." }, "sp_slo_url": { "type": "string", "description": "The SP SLO URL of the SAML provider." }, "sp_metadata_url": { "type": "string", "description": "The SP metadata URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/login_options_for_login": { "get": { "tags": [ "Dashboard Login Option" ], "summary": "List all login options (public)", "operationId": "listLoginOptionsForLogin", "description": "List login options. No authentication is required, and provider or policy/role details are not included in the response.", "parameters": [ { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "Name of the resource." } ], "responses": { "200": { "description": "Successfully retrieved the available login options for the dashboard login page.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "Array of login options", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "name": { "example": "API7 Integrated Authentication", "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option." }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "provider_type": { "type": "string", "enum": [ "ldap", "oidc", "saml", "built_in" ], "description": "The login option type.", "example": "built_in" }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/ldap/{login_option_id}/login": { "post": { "tags": [ "User" ], "summary": "Log in to API7 Enterprise using the LDAP username and password", "operationId": "LDAPLogin", "description": "Authenticate a user through the specified LDAP login option and create a dashboard session.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "description": "The username of the user.", "type": "string", "minLength": 1, "maxLength": 128, "example": "john" }, "password": { "type": "string", "description": "The password of the user.", "minLength": 1, "maxLength": 128, "example": "safe-password" }, "otp": { "description": "The two-factor authentication code. Required only when the account has 2FA enabled. Accepts a TOTP code from an authenticator app or a one-time recovery code.", "type": "string", "minLength": 1, "maxLength": 64 } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the login option.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "allOf": [ { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Name of the login option.", "example": "example-login" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "disable": { "type": "boolean", "description": "If true, disable the login option.", "default": false }, "role_mapping": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "description": "Unique identifier for the role.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "role_attribute_key": { "type": "string", "description": "The key used to identify the role attribute.", "example": "Position" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "example": "exact_match", "description": "The operation to apply on the role attribute." }, "role_attribute_value": { "type": "string", "description": "The value expected for the role attribute based on the operation.", "example": "Team Leader" } }, "required": [ "role_id", "role_attribute_key", "operation", "role_attribute_value" ] }, "description": "A list of role mappings defining operations and conditions under which roles are applied." }, "boundary_mapping": { "type": "array", "items": { "type": "object", "properties": { "permission_policy_id": { "description": "Unique identifier for the boundary permission policy.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "attribute_key": { "type": "string", "description": "The Name of the boundary permission policy attribute.", "example": "Group" }, "operation": { "type": "string", "enum": [ "exact_match", "contains_string", "exact_match_in_array", "contains_string_in_array" ], "description": "The operation to apply on the role attribute." }, "attribute_value": { "type": "string", "description": "The value expected for the boundary permission policy attribute based on the operation.", "example": "Finance" } }, "required": [ "permission_policy_id", "attribute_key", "operation", "attribute_value" ] }, "description": "A list of boundary mappings defining operations and conditions under which boundaries are applied." } } }, { "oneOf": [ { "title": "OIDC", "properties": { "provider_type": { "type": "string", "enum": [ "oidc" ], "description": "The login option type." }, "oidc_config": { "type": "object", "description": "OIDC configuration.", "required": [ "client_id", "issuer", "request_scopes", "root_url" ], "properties": { "client_id": { "type": "string", "description": "The client ID of the OIDC provider.", "example": "my-oidc-client-id" }, "client_secret": { "type": "string", "description": "The client secret of the OIDC provider.", "example": "s3cr3tK3yForOIDC" }, "issuer": { "type": "string", "description": "The issuer URL of the OIDC provider.", "example": "https://accounts.example.com" }, "request_scopes": { "type": "array", "items": { "type": "string" }, "description": "The request scopes of the OIDC provider.", "example": [ "openid", "email", "profile" ] }, "ssl_verify": { "type": "boolean", "description": "If true, verify the SSL certificate of the OIDC provider.", "default": true }, "callback_url": { "type": "string", "description": "The root URL for the OIDC provider used to generate the callback URL.", "example": "http://127.0.0.1:7080" }, "logout_url": { "type": "string", "description": "The logout URL of the OIDC provider.", "example": "https://accounts.example.com/logout" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "SAML", "properties": { "provider_type": { "type": "string", "enum": [ "saml" ], "description": "The login option type." }, "saml_config": { "type": "object", "description": "SAML configuration.", "required": [ "idp_metadata_url", "sp_root_url" ], "properties": { "idp_metadata_url": { "type": "string", "description": "The IdP metadata URL of the SAML provider." }, "sp_root_url": { "type": "string", "description": "The SP root URL of the SAML provider." }, "sp_acs_url": { "type": "string", "description": "The SP ACS URL of the SAML provider." }, "sp_slo_url": { "type": "string", "description": "The SP SLO URL of the SAML provider." }, "sp_metadata_url": { "type": "string", "description": "The SP metadata URL of the SAML provider." }, "sign_request": { "type": "boolean", "description": "Whether to sign the request of the SAML provider." }, "certificate": { "type": "string", "description": "The certificate of the SAML provider." }, "entity_id": { "type": "string", "description": "The entity ID of the SAML provider." }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } } } } } }, { "title": "LDAP", "properties": { "provider_type": { "type": "string", "enum": [ "ldap" ], "description": "The login option type." }, "ldap_config": { "type": "object", "description": "LDAP configuration.", "required": [ "host", "port", "base_dn", "bind_dn", "identifier" ], "properties": { "host": { "type": "string", "description": "The host domain of the LDAP server." }, "port": { "type": "string", "description": "The port ID of the LDAP server." }, "base_dn": { "type": "string", "description": "The base DN of the LDAP server." }, "bind_dn": { "type": "string", "description": "Search user bind DN." }, "bind_password": { "type": "string", "description": "Search user bind password." }, "identifier": { "type": "string", "description": "The identifier of the LDAP server. Together with the username, it forms the full DN.", "example": "cn" }, "attributes": { "type": "object", "description": "The attributes used to map the user information to API7 Enterprise.", "additionalProperties": { "type": "string" }, "example": { "first_name": "john", "last_name": "doe", "username": "johndoe" } }, "timeout": { "type": "integer", "description": "Timeout in seconds.", "default": 10, "minimum": 0 }, "use_ssl": { "type": "boolean", "description": "Set it to true if the LDAP server uses an encrypted TLS connection.", "default": false }, "ssl_verify": { "type": "boolean", "description": "Set it to false if you want to skip SSL certificate validation.", "default": true }, "root_ca_cert": { "type": "string", "description": "Set the data of your root CA certificate." }, "client_cert": { "type": "string", "description": "The client certificate." }, "client_key": { "type": "string", "description": "The client private key." } } } } }, { "title": "Built-in", "properties": { "provider_type": { "type": "string", "enum": [ "built_in" ], "description": "The login option type." }, "builtin_config": { "type": "object", "description": "Built-in configuration.", "properties": { "login_with_email": { "type": "boolean", "description": "If true, enable email login.", "default": false } } } } } ] } ] } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/ldap/{login_option_id}/logout": { "post": { "tags": [ "User" ], "summary": "Log out from API7 Enterprise using the LDAP username and password", "operationId": "LDAPLogout", "description": "Log out a session established via LDAP authentication for the specified login option.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } } } } }, "/api/cas/{login_option_id}/login": { "get": { "tags": [ "User" ], "summary": "Log in using the CAS provider", "operationId": "CASLogin", "description": "Start or complete CAS login for the selected login option, including CAS ticket processing.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." }, { "name": "ticket", "in": "query", "description": "The field of the CAS protocol.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to IdP.", "content": {} }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/cas/{login_option_id}/logout": { "get": { "tags": [ "User" ], "summary": "Log out using the CAS provider", "operationId": "CASLogout", "description": "Start CAS logout for the selected login option and redirect to the configured post-logout target.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." }, { "name": "redirect", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Redirect to the given URL after logout." } ], "responses": { "302": { "description": "Redirect to IdP.", "content": {} }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/oidc/{login_option_id}/login": { "get": { "tags": [ "User" ], "summary": "Log in using the OIDC provider", "operationId": "OIDCLogin", "description": "Start OIDC authentication by redirecting to the configured OpenID Connect provider for the selected login option.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "responses": { "307": { "description": "Redirect", "content": {} }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/oidc/{login_option_id}/callback": { "get": { "tags": [ "User" ], "summary": "Log in using the OIDC provider", "operationId": "OIDCCallback", "description": "Process OIDC callback parameters and complete authentication for the selected login option.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." }, { "name": "state", "in": "query", "description": "The field of the OIDC protocol.", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "The field of the OIDC protocol.", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Redirect to the home page.", "content": {} }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/oidc/{login_option_id}/logout": { "get": { "tags": [ "User" ], "summary": "Log out using the OIDC provider", "operationId": "OIDCLogout", "description": "Start OIDC logout flow and redirect through the provider logout endpoint for the selected login option.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "responses": { "307": { "description": "Redirect", "content": {} }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/version": { "get": { "tags": [ "Common" ], "summary": "Get Dashboard Version", "operationId": "getDashboardVersion", "description": "Return the current dashboard version information. Use this endpoint for compatibility checks and operational diagnostics.", "responses": { "200": { "description": "Successfully retrieved the dashboard version.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "description": "Dashboard version.", "type": "string", "example": "dev" } } } ] } } } } } } }, "/api/custom_plugins": { "get": { "tags": [ "Custom Plugin" ], "summary": "List all custom plugins", "operationId": "listCustomPlugins", "description": "List all uploaded custom plugins available in the current scope. Use pagination and search parameters to locate plugin packages by name or metadata.\n\n**Required IAM Permission:** Action `gateway:GetCustomPlugin`, Resource `arn:api7:gateway:gatewaysetting/*`", "parameters": [ { "name": "gateway_group_id", "description": "Gateway group ID.", "in": "query", "required": false, "schema": { "minimum": 1, "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "in": "query", "name": "name", "schema": { "type": "string" }, "description": "Name of the resource." } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of custom plugins.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "Array of custom plugins.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The name of the plugin.", "example": "route-id-register" }, "version": { "type": "string", "description": "The version of the plugin.", "example": "0.2" }, "source_code": { "type": "string", "description": "The source code for the plugin.", "example": "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" }, "file": { "type": "string", "description": "Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.", "example": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=" }, "catalog": { "type": "string", "description": "Plugin category, such as \"Traffic\" or \"Observability\".", "example": "General" }, "description": { "type": "string", "description": "A brief description of the plugin.", "example": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring." }, "documentation_link": { "type": "string", "description": "Link to the plugin's documentation.", "example": "https://docs.api7.ai/hub/route-id-register" }, "author": { "type": "string", "description": "Author of the plugin.", "example": "plugindev" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "is_obfuscated": { "type": "boolean", "description": "Whether the custom plugin’s source code is obfuscated into bytecode.", "example": false }, "gateway_groups": { "type": "array", "description": "An array of gateway group IDs that the custom plugin is associated with.", "items": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "post": { "tags": [ "Custom Plugin" ], "summary": "Create a custom plugin", "operationId": "createCustomPlugin", "description": "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.\n\n**Required IAM Permission:** Action `gateway:CreateCustomPlugin`, Resource `arn:api7:gateway:gatewaysetting/*`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog": { "type": "string", "description": "Plugin category, such as \"Traffic\" or \"Observability\".", "example": "General" }, "description": { "type": "string", "description": "A brief description of the plugin.", "example": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring." }, "documentation_link": { "type": "string", "description": "Link to the plugin's documentation.", "example": "https://docs.api7.ai/hub/route-id-register" }, "author": { "type": "string", "description": "Author of the plugin.", "example": "plugindev" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "gateway_groups": { "type": "array", "description": "An array of gateway group IDs that the custom plugin is associated with.", "items": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } }, "oneOf": [ { "title": "Plugin Source Code", "required": [ "source_code", "gateway_groups" ], "properties": { "source_code": { "type": "string", "description": "The source code for the plugin.", "example": "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" } } }, { "title": "Plugin File", "required": [ "file", "gateway_groups" ], "properties": { "file": { "type": "string", "description": "Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.", "example": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=" } } } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the custom plugin.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The name of the plugin.", "example": "route-id-register" }, "version": { "type": "string", "description": "The version of the plugin.", "example": "0.2" }, "source_code": { "type": "string", "description": "The source code for the plugin.", "example": "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" }, "file": { "type": "string", "description": "Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.", "example": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=" }, "catalog": { "type": "string", "description": "Plugin category, such as \"Traffic\" or \"Observability\".", "example": "General" }, "description": { "type": "string", "description": "A brief description of the plugin.", "example": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring." }, "documentation_link": { "type": "string", "description": "Link to the plugin's documentation.", "example": "https://docs.api7.ai/hub/route-id-register" }, "author": { "type": "string", "description": "Author of the plugin.", "example": "plugindev" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "is_obfuscated": { "type": "boolean", "description": "Whether the custom plugin’s source code is obfuscated into bytecode.", "example": false }, "gateway_groups": { "type": "array", "description": "An array of gateway group IDs that the custom plugin is associated with.", "items": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/custom_plugins/{custom_plugin_id}": { "get": { "tags": [ "Custom Plugin" ], "summary": "Get a custom plugin", "operationId": "getCustomPlugin", "description": "Retrieve metadata and configuration of a specific custom plugin package, including user-uploaded Lua or WASM plugin details.\n\n**Required IAM Permission:** Action `gateway:GetCustomPlugin`, Resource `arn:api7:gateway:gatewaysetting/*`", "parameters": [ { "name": "custom_plugin_id", "in": "path", "required": true, "description": "Custom plugin ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved or modified the custom plugin.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The name of the plugin.", "example": "route-id-register" }, "version": { "type": "string", "description": "The version of the plugin.", "example": "0.2" }, "source_code": { "type": "string", "description": "The source code for the plugin.", "example": "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" }, "file": { "type": "string", "description": "Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.", "example": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=" }, "catalog": { "type": "string", "description": "Plugin category, such as \"Traffic\" or \"Observability\".", "example": "General" }, "description": { "type": "string", "description": "A brief description of the plugin.", "example": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring." }, "documentation_link": { "type": "string", "description": "Link to the plugin's documentation.", "example": "https://docs.api7.ai/hub/route-id-register" }, "author": { "type": "string", "description": "Author of the plugin.", "example": "plugindev" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "is_obfuscated": { "type": "boolean", "description": "Whether the custom plugin’s source code is obfuscated into bytecode.", "example": false }, "gateway_groups": { "type": "array", "description": "An array of gateway group IDs that the custom plugin is associated with.", "items": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "put": { "tags": [ "Custom Plugin" ], "summary": "Update a custom plugin", "operationId": "putCustomPlugin", "description": "Update an existing custom plugin package and its metadata. Changes can affect plugin behavior where the plugin is enabled.\n\n**Required IAM Permission:** Action `gateway:UpdateCustomPlugin`, Resource `arn:api7:gateway:gatewaysetting/*`", "parameters": [ { "name": "custom_plugin_id", "in": "path", "required": true, "description": "Custom plugin ID.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "catalog": { "type": "string", "description": "Plugin category, such as \"Traffic\" or \"Observability\".", "example": "General" }, "description": { "type": "string", "description": "A brief description of the plugin.", "example": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring." }, "documentation_link": { "type": "string", "description": "Link to the plugin's documentation.", "example": "https://docs.api7.ai/hub/route-id-register" }, "author": { "type": "string", "description": "Author of the plugin.", "example": "plugindev" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "gateway_groups": { "type": "array", "description": "An array of gateway group IDs that the custom plugin is associated with.", "items": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } } }, "oneOf": [ { "title": "Plugin Source Code", "required": [ "source_code", "gateway_groups" ], "properties": { "source_code": { "type": "string", "description": "The source code for the plugin.", "example": "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" } } }, { "title": "Plugin File", "required": [ "file", "gateway_groups" ], "properties": { "file": { "type": "string", "description": "Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.", "example": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=" } } } ] } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the custom plugin.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "type": "string", "description": "The name of the plugin.", "example": "route-id-register" }, "version": { "type": "string", "description": "The version of the plugin.", "example": "0.2" }, "source_code": { "type": "string", "description": "The source code for the plugin.", "example": "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" }, "file": { "type": "string", "description": "Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.", "example": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=" }, "catalog": { "type": "string", "description": "Plugin category, such as \"Traffic\" or \"Observability\".", "example": "General" }, "description": { "type": "string", "description": "A brief description of the plugin.", "example": "This plugin records the matched route’s ID into an Nginx variable ($route_id) for use in logging and monitoring." }, "documentation_link": { "type": "string", "description": "Link to the plugin's documentation.", "example": "https://docs.api7.ai/hub/route-id-register" }, "author": { "type": "string", "description": "Author of the plugin.", "example": "plugindev" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" }, "is_obfuscated": { "type": "boolean", "description": "Whether the custom plugin’s source code is obfuscated into bytecode.", "example": false }, "gateway_groups": { "type": "array", "description": "An array of gateway group IDs that the custom plugin is associated with.", "items": { "description": "The gateway group ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } }, "delete": { "tags": [ "Custom Plugin" ], "summary": "Delete a custom plugin", "operationId": "deleteCustomPlugin", "description": "Delete a custom plugin package from the control plane. Ensure the plugin is no longer referenced by services or routes before removal.\n\n**Required IAM Permission:** Action `gateway:DeleteCustomPlugin`, Resource `arn:api7:gateway:gatewaysetting/*`", "parameters": [ { "name": "custom_plugin_id", "in": "path", "required": true, "description": "Custom plugin ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/custom_plugins/code/parse": { "put": { "tags": [ "Custom Plugin" ], "summary": "Parse custom plugin code", "operationId": "parseCustomPluginCode", "description": "Parse and validate custom plugin source payload to extract plugin metadata and detect structural issues before creating or updating a plugin.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "description": "Base64-encoded ZIP archive that contains the plugin package. The archive includes the plugin code and the plugin metadata.", "example": "bG9jYWwgY29yZSA9IHJlcXVpcmUoImFwaXNpeC5jb3JlIikKbG9jYWwgbmd4ID0gbmd4Cgpsb2NhbCBzY2hlbWEgPSB7CiAgICB0eXBlID0gIm9iamVjdCIKfQoKbG9jYWwgcGx1Z2luX25hbWUgPSAicm91dGUtaWQtcmVnaXN0ZXIiCgpsb2NhbCBfTSA9IHsKICB2ZXJzaW9uID0gMC4yLAogIHByaW9yaXR5ID0gMSwKICBuYW1lID0gcGx1Z2luX25hbWUsCiAgc2NoZW1hID0gc2NoZW1hLAogIHNjb3BlID0gImdsb2JhbCIsCn0KCmZ1bmN0aW9uIF9NLmNoZWNrX3NjaGVtYShjb25mKQogIHJldHVybiBjb3JlLnNjaGVtYS5jaGVjayhzY2hlbWEsIGNvbmYpOwplbmQKCmZ1bmN0aW9uIF9NLmxvZyhjb25mLCBjdHgpCiAgaWYgY3R4LnZhci5yb3V0ZV9pZCB0aGVuCiAgICBuZ3gudmFyLnJvdXRlX2lkID0gY3R4LnZhci5yb3V0ZV9pZAogIGVuZAplbmQKCnJldHVybiBfTQo=" } } } } } }, "responses": { "200": { "description": "Successfully parsed the custom plugin code and extracted metadata.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the plugin.", "example": "route-id-register" }, "version": { "type": "string", "description": "The version of the plugin.", "example": "0.2" }, "catalog": { "type": "string", "description": "Plugin category, such as \"Traffic\" or \"Observability\".", "example": "General" }, "description": { "type": "string", "description": "A brief description of the plugin." }, "documentation_link": { "type": "string", "description": "Link to the plugin's documentation.", "example": "https://docs.api7.ai/hub/route-id-register" }, "author": { "type": "string", "description": "Author of the plugin.", "example": "plugindev" }, "logo": { "type": "string", "description": "The base64-encoded logo image.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAH4SURBVHgBrVVLUhsxEH3SaBJSxJQWLLJKzAkClcqCVcINkhuYk6RygnCDkBOYI3iXTVKQE9ipggIGKKb42TAjNWrbY0+BkcY2b6ceqV/3688Ac6CrF+r/tfzmuyMxI25rL75klO+exDbFcxP0luItAjXbKteSsOe7qzAFWBJpbZOIVhNlkAkgyvHP96ZyBiyJMGaXnd8JQhJZgNBZSzGfRKS1LiRxR822dpwPPgq/PAyvRCzJnb1pukhXC9uZi5ylGfgPEzyZQbcWNwpJChtLcxyZ8WOaMYPua/XZRffzoT1xzq0Yn3vGX+B+EJOMr67yFkXZivO1XdjOnTRpROVr6XqKDmYh6JO4xy8vs00mMpJ2kpI0QwTl8RKUiZSlX+9yhcWSPqIiQaVBEyQ/Lbi2X7EK19LiULlOArWqvK00aC7wUSctWom3WcQZNH6/QT30VqACerX4HMMhY+yrfFxwgW3H9339aHLBgwQ8bG4e2sWZu+lAPSq4m0VsfDxF66E9KJE02Uge099Bj5ynzntjknNGuMgk3hd5JqU1McReluOrbx7CRRaynwGvCd5DIzOw5Vb1RmjYghkQdxCVNuhAks0PZ9hBBXgJSEPfGqoXPxdUkGQq8NK7WFL0Zxn0dxk/MAO8GQhX4E6cTSXJVAQnsdHXBmvzSHIP3R3bZScnj8UAAAAASUVORK5CYII=" } } } } } ] } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/saml/{login_option_id}/login": { "get": { "tags": [ "User" ], "summary": "SAML login (redirect to IdP and call back to Dashboard)", "operationId": "SAMLLogin", "description": "Start SAML 2.0 login by redirecting to the identity provider and preparing for ACS callback handling.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." }, { "name": "redirect_uri", "in": "query", "schema": { "type": "string", "minLength": 1, "pattern": "^/" }, "description": "Path to be redirected after callback." } ], "responses": { "302": { "description": "Redirect to IdP.", "content": {} }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/saml/{login_option_id}/logout": { "get": { "tags": [ "User" ], "summary": "SAML Logout (redirect to IdP and call back to Dashboard)", "operationId": "SAMLLogout", "description": "Start SAML 2.0 logout by redirecting through the identity provider for the selected login option.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." }, { "name": "redirect_uri", "in": "query", "schema": { "type": "string", "minLength": 1, "pattern": "^/" }, "description": "Path to be redirected after callback." } ], "responses": { "302": { "description": "Redirect to IdP.", "content": {} } } } }, "/api/saml/{login_option_id}/acs": { "post": { "operationId": "SAMLACSCallback", "tags": [ "User" ], "summary": "SAML ACS/SLO callback (from IdP to Dashboard)", "description": "Handle SAML ACS/SLO callback payloads posted by the identity provider for the selected login option.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "SAMLResponse" ], "properties": { "SAMLResponse": { "type": "string", "description": "Base64 encoded SAML response" }, "RelayState": { "type": "string", "description": "State information to be relayed with the response" } } } } } }, "responses": { "302": { "description": "Redirect to IdP.", "content": {} } } } }, "/api/saml/{login_option_id}/slo": { "get": { "tags": [ "User" ], "summary": "SAML ACS/SLO callback (from IdP to Dashboard)", "operationId": "SAMLSLO", "description": "Handle SAML ACS/SLO callback query parameters from the identity provider and finalize SAML sign-in or sign-out.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." }, { "name": "SAMLResponse", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Base64 encoded SAML response." }, { "name": "RelayState", "in": "query", "required": false, "schema": { "type": "string" }, "description": "State information to be relayed with the response." } ], "responses": { "302": { "description": "Redirect to IdP.", "content": {} } } }, "post": { "operationId": "SAMLSLOCallback", "tags": [ "User" ], "summary": "SAML ACS/SLO callback (from IdP to Dashboard)", "description": "Handle SAML ACS/SLO callback payloads posted by the identity provider for the selected login option.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "SAMLResponse" ], "properties": { "SAMLResponse": { "type": "string", "description": "Base64 encoded SAML response" }, "RelayState": { "type": "string", "description": "State information to be relayed with the response" } } } } } }, "responses": { "302": { "description": "Redirect to IdP.", "content": {} } } } }, "/api/saml/{login_option_id}/metadata": { "get": { "tags": [ "User" ], "summary": "SAML SP metadata", "operationId": "SAMLMetadata", "description": "Get SAML service provider metadata XML for the specified login option to help configure identity-provider trust.", "parameters": [ { "name": "login_option_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Login option ID." } ], "responses": { "200": { "description": "saml metadata xml response", "content": { "application/samlmetadata+xml": { "schema": { "type": "string" } } } } } } }, "/api/parse_certificate": { "put": { "tags": [ "SSL" ], "summary": "Parse an SSL certificate", "operationId": "parseCertificate", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } }, "required": [ "cert" ] } } } }, "responses": { "200": { "description": "Successfully parsed the certificate and returned its metadata.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of certificates metadata.", "items": { "type": "object", "properties": { "common_name": { "type": "string", "description": "The common name of the certificate.", "example": "example.com" }, "subject_alt_names": { "type": "array", "description": "The subject alternative names of the certificate.", "items": { "type": "string", "example": "www.example.com" } }, "snis": { "type": "array", "items": { "type": "string" } }, "not_before": { "type": "string", "format": "date-time", "nullable": true }, "not_after": { "type": "string", "format": "date-time", "nullable": true }, "subject": { "type": "string" }, "issuer": { "type": "string" }, "serial_number": { "type": "string" }, "signature_algorithm": { "type": "string" }, "extensions": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/validate_cert_key": { "put": { "tags": [ "SSL" ], "summary": "Validate an SSL certificate and key", "operationId": "validateCertKey", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "cert", "key" ] } } } }, "responses": { "200": { "description": "Successfully validated the SSL certificate and key pair.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "value": { "type": "boolean", "description": "If true, the SSL certificate and key are valid." } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/contact_points": { "post": { "tags": [ "Contact Point" ], "summary": "Create a contact point", "operationId": "createContactPoint", "description": "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.\n\n**Required IAM Permission:** Action `iam:CreateContactPoint`, Resource `arn:api7:iam:contactpoint/*`", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test", "minLength": 1, "maxLength": 256 }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "oneOf": [ { "title": "Email", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "email" ] }, "email_config": { "type": "object", "description": "Contact point email configurations.", "properties": { "email": { "type": "array", "items": { "type": "string", "format": "email" } } } } }, "required": [ "email_config" ] }, { "title": "Webhook", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "webhook" ] }, "webhook_config": { "type": "object", "description": "Contact point webhook configurations.", "properties": { "ssl_verify": { "type": "boolean", "description": "If true, perform SSL verification." }, "url": { "type": "string", "description": "Webhook URL.", "format": "url", "minLength": 1, "maxLength": 1024 }, "method": { "type": "string", "description": "HTTP method of the webhook request.", "default": "POST", "enum": [ "POST" ] }, "headers": { "type": "array", "description": "Extra HTTP headers to take when sending requests.", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-_a-zA-Z0-9]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } }, "required": [ "webhook_config" ] } ] } ], "required": [ "name", "type" ] } } } }, "responses": { "200": { "description": "Contact point created successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test", "minLength": 1, "maxLength": 256 }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "oneOf": [ { "title": "Email", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "email" ] }, "email_config": { "type": "object", "description": "Contact point email configurations.", "properties": { "email": { "type": "array", "items": { "type": "string", "format": "email" } } } } }, "required": [ "email_config" ] }, { "title": "Webhook", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "webhook" ] }, "webhook_config": { "type": "object", "description": "Contact point webhook configurations.", "properties": { "ssl_verify": { "type": "boolean", "description": "If true, perform SSL verification." }, "url": { "type": "string", "description": "Webhook URL.", "format": "url", "minLength": 1, "maxLength": 1024 }, "method": { "type": "string", "description": "HTTP method of the webhook request.", "default": "POST", "enum": [ "POST" ] }, "headers": { "type": "array", "description": "Extra HTTP headers to take when sending requests.", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-_a-zA-Z0-9]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } }, "required": [ "webhook_config" ] } ] } ], "required": [ "name", "type" ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "get": { "tags": [ "Contact Point" ], "summary": "List Contact Points", "operationId": "listContactPoints", "description": "List contact points available for alert notification delivery. Use filters and pagination to locate channels by type, labels, or search terms.\n\n**Required IAM Permission:** Action `iam:GetContactPoint`, Resource `arn:api7:iam:contactpoint/%s`", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "email", "webhook" ] } }, { "name": "labels", "in": "query", "required": false, "description": "Label(s) to filter resources by. The format is `labels[key]=value` and should be URL-encoded.", "schema": { "type": "string", "minLength": 1, "example": "labels%5Bversion%5D=v2" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "order_by", "in": "query", "description": "Index to order resources by.", "schema": { "type": "string", "default": "updated_at", "enum": [ "created_at", "updated_at" ], "description": "Field used to order resources, either `created_at` or `updated_at`." } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of contact points.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of contact points.", "items": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test", "minLength": 1, "maxLength": 256 }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "oneOf": [ { "title": "Email", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "email" ] }, "email_config": { "type": "object", "description": "Contact point email configurations.", "properties": { "email": { "type": "array", "items": { "type": "string", "format": "email" } } } } }, "required": [ "email_config" ] }, { "title": "Webhook", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "webhook" ] }, "webhook_config": { "type": "object", "description": "Contact point webhook configurations.", "properties": { "ssl_verify": { "type": "boolean", "description": "If true, perform SSL verification." }, "url": { "type": "string", "description": "Webhook URL.", "format": "url", "minLength": 1, "maxLength": 1024 }, "method": { "type": "string", "description": "HTTP method of the webhook request.", "default": "POST", "enum": [ "POST" ] }, "headers": { "type": "array", "description": "Extra HTTP headers to take when sending requests.", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-_a-zA-Z0-9]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } }, "required": [ "webhook_config" ] } ] } ], "required": [ "name", "type" ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/contact_points/{contact_point_id}": { "get": { "tags": [ "Contact Point" ], "summary": "Get a contact point", "operationId": "getContactPoint", "description": "Retrieve details of a specific contact point, including its configuration and metadata. Use this before updating or validating notification settings.\n\n**Required IAM Permission:** Action `iam:GetContactPoint`, Resource `arn:api7:iam:contactpoint/%s`", "parameters": [ { "name": "contact_point_id", "in": "path", "required": true, "description": "Contact point ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successfully retrieved the contact point.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test", "minLength": 1, "maxLength": 256 }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "oneOf": [ { "title": "Email", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "email" ] }, "email_config": { "type": "object", "description": "Contact point email configurations.", "properties": { "email": { "type": "array", "items": { "type": "string", "format": "email" } } } } }, "required": [ "email_config" ] }, { "title": "Webhook", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "webhook" ] }, "webhook_config": { "type": "object", "description": "Contact point webhook configurations.", "properties": { "ssl_verify": { "type": "boolean", "description": "If true, perform SSL verification." }, "url": { "type": "string", "description": "Webhook URL.", "format": "url", "minLength": 1, "maxLength": 1024 }, "method": { "type": "string", "description": "HTTP method of the webhook request.", "default": "POST", "enum": [ "POST" ] }, "headers": { "type": "array", "description": "Extra HTTP headers to take when sending requests.", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-_a-zA-Z0-9]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } }, "required": [ "webhook_config" ] } ] } ], "required": [ "name", "type" ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "Contact Point" ], "summary": "Update a contact point", "operationId": "putContactPoint", "description": "Update a contact point configuration, such as destination address, authentication details, or labels. Changes take effect for subsequent alert notifications.\n\n**Required IAM Permission:** Action `iam:UpdateContactPoint`, Resource `arn:api7:iam:contactpoint/%s`", "parameters": [ { "name": "contact_point_id", "in": "path", "required": true, "description": "Contact point ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test", "minLength": 1, "maxLength": 256 }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "oneOf": [ { "title": "Email", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "email" ] }, "email_config": { "type": "object", "description": "Contact point email configurations.", "properties": { "email": { "type": "array", "items": { "type": "string", "format": "email" } } } } }, "required": [ "email_config" ] }, { "title": "Webhook", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "webhook" ] }, "webhook_config": { "type": "object", "description": "Contact point webhook configurations.", "properties": { "ssl_verify": { "type": "boolean", "description": "If true, perform SSL verification." }, "url": { "type": "string", "description": "Webhook URL.", "format": "url", "minLength": 1, "maxLength": 1024 }, "method": { "type": "string", "description": "HTTP method of the webhook request.", "default": "POST", "enum": [ "POST" ] }, "headers": { "type": "array", "description": "Extra HTTP headers to take when sending requests.", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-_a-zA-Z0-9]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } }, "required": [ "webhook_config" ] } ] } ], "required": [ "name", "type" ] } } } }, "responses": { "200": { "description": "Contact point updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "allOf": [ { "allOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test", "minLength": 1, "maxLength": 256 }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } }, { "oneOf": [ { "title": "Email", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "email" ] }, "email_config": { "type": "object", "description": "Contact point email configurations.", "properties": { "email": { "type": "array", "items": { "type": "string", "format": "email" } } } } }, "required": [ "email_config" ] }, { "title": "Webhook", "type": "object", "properties": { "type": { "type": "string", "description": "Type of contact point.", "enum": [ "webhook" ] }, "webhook_config": { "type": "object", "description": "Contact point webhook configurations.", "properties": { "ssl_verify": { "type": "boolean", "description": "If true, perform SSL verification." }, "url": { "type": "string", "description": "Webhook URL.", "format": "url", "minLength": 1, "maxLength": 1024 }, "method": { "type": "string", "description": "HTTP method of the webhook request.", "default": "POST", "enum": [ "POST" ] }, "headers": { "type": "array", "description": "Extra HTTP headers to take when sending requests.", "minItems": 1, "maxItems": 16, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[-_a-zA-Z0-9]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } }, "required": [ "webhook_config" ] } ] } ], "required": [ "name", "type" ] }, { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } ] } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "Contact Point" ], "summary": "Delete a contact point", "operationId": "deleteContactPoint", "description": "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.\n\n**Required IAM Permission:** Action `iam:DeleteContactPoint`, Resource `arn:api7:iam:contactpoint/%s`", "parameters": [ { "name": "contact_point_id", "in": "path", "required": true, "description": "Contact point ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/contact_points/{contact_point_id}/notification_logs": { "get": { "tags": [ "Contact Point" ], "summary": "List notification logs of a contact point", "operationId": "listContactPointNotificationLogs", "description": "List notification delivery logs for a contact point, including status, target resource type, and timestamps. Use this to troubleshoot failed or delayed alert notifications.\n\n**Required IAM Permission:** Action `iam:GetContactPoint`, Resource `arn:api7:iam:contactpoint/%s`", "parameters": [ { "name": "contact_point_id", "in": "path", "required": true, "description": "Contact point ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "in": "query", "name": "start_at", "description": "Start at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "in": "query", "name": "end_at", "description": "End at timestamp to filter the audit logs.", "schema": { "type": "integer" } }, { "name": "resource_type", "in": "query", "schema": { "type": "string", "description": "Type of notification.", "enum": [ "alert_policy", "api_product_notification" ] } }, { "name": "status", "in": "query", "description": "Notification sending status.", "schema": { "type": "string", "enum": [ "success", "failed" ] } }, { "name": "order_by", "in": "query", "description": "Index to order the notifications by.", "schema": { "type": "string", "default": "send_time", "enum": [ "send_time" ] } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of notification logs.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of notification logs.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "contact_point_name": { "type": "string", "description": "Name of the contact point.", "example": "cp-docs-test" }, "resource_type": { "type": "string", "description": "Type of notification.", "enum": [ "alert_policy", "api_product_notification" ] }, "resource_id": { "description": "The resource ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "resource_name": { "example": "Weather Insights API", "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100 }, "status": { "type": "string", "description": "Notification sending status.", "enum": [ "success", "failed" ], "example": "failed" }, "send_time": { "type": "integer", "example": 1759649130, "description": "The time when the notification is sent." }, "request": { "type": "string", "description": "Request information.", "example": "{\"from\": \"test.send@api7.ai\", \"to\": \"test.receive@api7.ai\", \"subject\": \"API7 Notification\", \"content\": \"This is a test notification.\"}" }, "response": { "type": "string", "description": "Response from the server.", "example": "450 The domain must be verified in your account to send emails." } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/contact_points/{contact_point_id}/usages": { "get": { "tags": [ "Contact Point" ], "summary": "List a contact point usages", "operationId": "getContactPointUsages", "description": "List resources that currently reference the specified contact point. Check usage before deletion or major edits to understand downstream impact.\n\n**Required IAM Permission:** Action `iam:GetContactPoint`, Resource `arn:api7:iam:contactpoint/%s`", "parameters": [ { "name": "contact_point_id", "in": "path", "required": true, "description": "Contact point ID.", "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, { "name": "resource_type", "in": "query", "schema": { "type": "string", "description": "Type of notification.", "enum": [ "alert_policy", "api_product_notification" ] } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of contact point usages.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of contact point usages.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "resource_type": { "type": "string", "description": "Type of notification.", "enum": [ "alert_policy", "api_product_notification" ] }, "resource_id": { "description": "The resource ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "b32e678e-7f6b-4a50-b113-550621ed4c01" }, "resource_name": { "description": "The resource name.", "example": "Weather Insights API", "type": "string", "minLength": 1, "maxLength": 100 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/resource_names": { "post": { "tags": [ "Common" ], "summary": "Get resource names", "operationId": "queryResourceNames", "description": "Query resource names by conditions in the request payload to support selectors, autocomplete, or dependency checks in UI workflows.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "Gateway Groups / Contact Points", "type": "object", "properties": { "resource_type": { "description": "Resource type.", "type": "string", "enum": [ "gateway_group", "contact_point" ] }, "ids": { "type": "array", "uniqueItems": true, "minItems": 1, "description": "An array of resource IDs.", "items": { "type": "string", "minLength": 1 } } }, "required": [ "resource_type", "ids" ], "additionalProperties": false }, { "title": "Resources in a Gateway Group", "type": "object", "properties": { "resource_type": { "type": "string", "description": "Resource type.", "enum": [ "sni", "certificate", "ca_certificate", "published_service", "published_route" ] }, "ids": { "type": "array", "uniqueItems": true, "minItems": 1, "description": "An array of resource IDs.", "items": { "type": "string", "minLength": 1 } }, "gateway_group_id": { "type": "string", "description": "The gateway group ID.", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bc1b95c9-b348-4832-acc3-e257d2342df1" } }, "required": [ "resource_type", "ids", "gateway_group_id" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Successfully resolved the resource IDs to their display names.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "additionalProperties": { "type": "string" } } } } ] }, "example": { "value": { "b5f57bda-b52b-41f6-9a30-a4c6442a3a74": "gateway-group-1", "f6ef6104-32a3-4382-a4b8-07cc17c466d8": "gateway-group-2" } } } } }, "400": { "description": "Invalid arguments. Error details will be provided in the response.", "content": {} } } } }, "/api/approvals": { "get": { "tags": [ "Approval" ], "summary": "List approvals", "operationId": "listApprovals", "description": "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.\n\n**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/*`", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "description": "Approval status.", "enum": [ "pending", "finished" ] } }, { "name": "result", "in": "query", "schema": { "type": "string", "description": "Approval outcome.", "enum": [ "accepted", "rejected", "cancelled" ] } }, { "name": "event", "in": "query", "schema": { "type": "string", "description": "Approval event.", "enum": [ "api_product_subscription", "developer_registration" ] } }, { "name": "resource_type", "in": "query", "schema": { "type": "string", "description": "Resource type.", "enum": [ "api_product", "developer" ] } }, { "name": "resource_name", "in": "query", "description": "Resource name.", "schema": { "type": "string" } }, { "name": "operator_name", "description": "Operator name.", "in": "query", "schema": { "type": "string" } }, { "name": "applicant_name", "in": "query", "description": "Applicant name.", "schema": { "type": "string" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "order_by", "in": "query", "schema": { "type": "string", "default": "applied_at", "description": "Index to order approvals by.", "enum": [ "applied_at", "resource_name", "operated_at" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of approval requests.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "The array of approval.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 }, "event": { "type": "string", "description": "Approval event.", "enum": [ "api_product_subscription", "developer_registration" ] }, "resource_type": { "type": "string", "description": "Resource type.", "enum": [ "api_product", "developer" ] }, "resource_id": { "description": "The resource ID.", "type": "string", "example": "cf232ad4-2e9a-4dc0-ad6f-9c1a898465ae" }, "resource_name": { "type": "string", "description": "Resource name.", "example": "Weather Insights API" }, "applicant_type": { "type": "string", "description": "Applicant type.", "enum": [ "developer" ] }, "applicant_id": { "type": "string", "description": "When `applicant_type` is `developer`, the applicant ID is the developer ID.", "example": "78c93683-3eb3-4129-bb57-3a564a0ab2b0" }, "applicant_name": { "type": "string", "description": "When `applicant_type` is `developer`, the applicant name is the developer name.", "example": "dev1" }, "applied_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "result": { "type": "string", "description": "Approval outcome.", "enum": [ "accepted", "rejected", "cancelled" ] }, "operator_id": { "type": "string", "description": "Operator ID.", "example": "bf073ca7-ada6-4e75-be80-730436798cce" }, "operator_name": { "type": "string", "description": "Operator name.", "example": "admin1" }, "operated_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "portal_id": { "type": "string", "description": "Portal ID." }, "portal_name": { "type": "string", "description": "Portal name." }, "status": { "type": "string", "description": "Approval status.", "enum": [ "pending", "finished" ] } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/approvals/{approval_id}/accept": { "post": { "tags": [ "Approval" ], "summary": "Accept an approval request", "operationId": "acceptApproval", "description": "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.\n\n**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/*`", "parameters": [ { "name": "approval_id", "in": "path", "description": "Approval ID.", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/approvals/{approval_id}/reject": { "post": { "tags": [ "Approval" ], "summary": "Reject an approval request", "operationId": "rejectApproval", "description": "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.\n\n**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/*`", "parameters": [ { "name": "approval_id", "in": "path", "description": "Approval ID.", "required": true, "schema": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/files": { "post": { "tags": [ "File" ], "summary": "Upload a file", "operationId": "uploadFile", "description": "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.", "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Original file name.", "schema": { "type": "string" }, "example": "petstore-api.json" } ], "requestBody": { "description": "Raw file content (maximum 10 MiB).", "content": { "application/octet-stream": {} } }, "responses": { "200": { "description": "File uploaded successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the uploaded file.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "description": "Original file name.", "example": "petstore-api.json" }, "mime_type": { "type": "string", "description": "Detected MIME type of the file.", "example": "application/json" }, "size": { "type": "integer", "description": "Original file size in bytes.", "example": 12345 }, "created_at": { "type": "integer", "description": "Upload timestamp (Unix epoch).", "example": 1711234567 } } } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/files/{file_id}": { "get": { "tags": [ "File" ], "summary": "Download file content", "operationId": "getFileContent", "description": "Download the original content of an uploaded file.", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the file." } ], "responses": { "200": { "description": "File content returned successfully.", "content": { "application/json": { "schema": { "type": "string" } }, "text/yaml": { "schema": { "type": "string" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/model_catalogs": { "get": { "tags": [ "Model Catalog" ], "summary": "List model catalog entries", "operationId": "listModelCatalogs", "description": "IAM Action: `ai_gateway:ListModelCatalogs`, Resource: `arn:api7:ai_gateway:modelcatalog/*`\nReturns 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.", "parameters": [ { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" }, { "name": "order_by", "in": "query", "description": "Field used to order catalog entries.", "schema": { "type": "string", "enum": [ "provider", "model", "name", "status", "created_at", "updated_at" ], "default": "provider" } }, { "name": "provider", "in": "query", "description": "Filter catalog entries by canonical provider.", "schema": { "type": "string", "example": "gemini" } }, { "name": "status", "in": "query", "description": "Filter catalog entries by status.", "schema": { "type": "string", "description": "Current status of the catalog entry.", "enum": [ "active", "deprecated" ] } }, { "name": "compact", "in": "query", "description": "Return the compact dropdown-oriented item shape when true.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successfully retrieved the paginated model catalog.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of model catalog items. When `compact=true`, each item uses the compact shape.", "items": { "oneOf": [ { "type": "object", "description": "A normalized model entry imported from the upstream model catalog source.", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "provider": { "type": "string", "description": "Canonical provider identifier used by AI model selection.", "example": "gemini" }, "model": { "type": "string", "description": "Upstream model identifier as returned by the source.", "example": "anthropic.claude-3-5-sonnet-20240620-v1:0" }, "name": { "type": "string", "description": "Human-readable model name from the upstream source.", "example": "Gemini 1.5 Pro" }, "status": { "type": "string", "description": "Current status of the catalog entry.", "enum": [ "active", "deprecated" ] }, "source": { "type": "object", "nullable": true, "description": "Flattened upstream model object plus `provider`, preserving source fidelity for troubleshooting.", "properties": { "provider": { "type": "string", "example": "google" } }, "additionalProperties": true }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } }, { "type": "object", "description": "Minimal catalog entry shape for dropdown selection.", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "provider": { "type": "string", "description": "Canonical provider identifier used by AI model selection.", "example": "openai" }, "model": { "type": "string", "description": "Upstream model identifier as stored from the source; it may include a provider-like prefix segment.", "example": "gpt-4o" }, "name": { "type": "string", "description": "Human-readable model name from the upstream source.", "example": "GPT-4o" } } } ] } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/model_catalogs/sync": { "post": { "tags": [ "Model Catalog" ], "summary": "Trigger a manual model catalog sync", "operationId": "syncModelCatalog", "description": "IAM Action: `ai_gateway:SyncModelCatalog`, Resource: `arn:api7:ai_gateway:modelcatalog/*`\nTriggers 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.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Empty request body reserved for future manual sync options." } } } }, "responses": { "200": { "description": "Successfully completed the manual model catalog sync request.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "Structured result returned by the manual sync API.", "properties": { "success": { "type": "boolean", "description": "Whether the synchronization completed successfully." }, "error_message": { "type": "string", "description": "Error summary for failed manual sync attempts.", "example": "unexpected HTTP status: 503" }, "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "nullable": true, "description": "HTTP status code returned by the upstream source, when available.", "example": 200 }, "duration_ms": { "type": "integer", "format": "int64", "minimum": 0, "description": "Total elapsed time of the synchronization run in milliseconds.", "example": 431 }, "diff": { "allOf": [ { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } ], "description": "JSON Patch snapshot diff for successful syncs." }, "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "409": { "description": "Conflict — A resource with the same unique identifier (e.g., name) already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/model_sync_logs": { "get": { "tags": [ "Model Catalog" ], "summary": "List model catalog sync logs", "operationId": "listModelSyncLogs", "description": "IAM Action: `ai_gateway:ListModelSyncLogs`, Resource: `arn:api7:ai_gateway:modelcatalog/*`\nReturns synchronization history entries, including execution status and structured diff information.", "parameters": [ { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "order_by", "in": "query", "description": "Field used to order sync log entries.", "schema": { "type": "string", "enum": [ "started_at", "completed_at", "duration_ms", "http_status", "status", "trigger_type", "created_at" ], "default": "started_at" } }, { "name": "trigger_type", "in": "query", "description": "Filter logs by trigger source.", "schema": { "type": "string", "description": "Source that triggered the synchronization run.", "enum": [ "scheduled", "manual" ] } }, { "name": "status", "in": "query", "description": "Filter logs by execution status.", "schema": { "type": "string", "description": "Final or current execution status of the synchronization run.", "enum": [ "running", "success", "failed" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated model sync logs.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of model catalog sync log entries.", "items": { "type": "object", "description": "Audit record for one model catalog synchronization attempt.", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "trigger_type": { "type": "string", "description": "Source that triggered the synchronization run.", "enum": [ "scheduled", "manual" ] }, "status": { "type": "string", "description": "Final or current execution status of the synchronization run.", "enum": [ "running", "success", "failed" ] }, "endpoint": { "type": "string", "description": "Sanitized source endpoint contacted during the synchronization attempt.", "example": "https://models.dev/api.json" }, "started_at": { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 }, "completed_at": { "allOf": [ { "description": "The object timestamp.", "type": "integer", "minimum": 0, "example": 1742288230 } ], "nullable": true, "description": "Completion time of the synchronization attempt. Null while a run is still in progress." }, "duration_ms": { "type": "integer", "format": "int64", "minimum": 0, "nullable": true, "description": "Total elapsed time of the synchronization run in milliseconds.", "example": 431 }, "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "nullable": true, "description": "HTTP status code returned by the upstream source, when available.", "example": 200 }, "error_message": { "type": "string", "nullable": true, "description": "Error summary when the synchronization failed or was skipped.", "example": "unexpected HTTP status: 503" }, "diff": { "allOf": [ { "type": "array", "description": "JSON Patch payload as defined by [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902). See [JSON Patch](https://jsonpatch.com) for more information.", "items": { "type": "object", "oneOf": [ { "title": "add/replace", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "add", "replace" ] }, "path": { "type": "string", "description": "Path to the field to be replaced or added. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format.", "example": "/name" }, "value": { "description": "Value to be added or replaced.", "example": "new-name" } }, "required": [ "op", "path", "value" ] }, { "title": "remove", "properties": { "op": { "type": "string", "description": "The operation to be performed.", "enum": [ "remove" ] }, "path": { "type": "string", "description": "Path to the field to be removed. Path should follow the [JSON Pointer](https://jsonpatch.com/#json-pointer) format." } }, "required": [ "op", "path" ] } ] } } ], "nullable": true, "description": "RFC 6902 JSON Patch operations for the synchronization result." }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups": { "get": { "tags": [ "AI Gateway Group" ], "summary": "List all AI Gateway groups", "operationId": "listAIGatewayGroups", "description": "Returns a paginated list of all AI Gateway groups (AISIX clusters).", "parameters": [ { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Condition to search resources by.", "example": "version%3Dv2" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of AI Gateway groups.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of AI Gateway groups.", "items": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "AI Gateway group description.", "example": "My AI Gateway group." }, "config": { "type": "object", "description": "Configuration for the AI Gateway group.", "properties": { "image_tag": { "type": "string", "description": "The AISIX (AI Gateway) image tag to deploy.", "example": "latest" } } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "post": { "tags": [ "AI Gateway Group" ], "summary": "Create an AI Gateway group", "operationId": "createAIGatewayGroup", "description": "IAM Action: `ai_gateway:CreateAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/*`\nCreates a new AI Gateway group (AISIX cluster).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "AI Gateway group description.", "example": "My AI Gateway group." }, "config": { "type": "object", "description": "Configuration for the AI Gateway group.", "properties": { "image_tag": { "type": "string", "description": "The AISIX (AI Gateway) image tag to deploy.", "example": "latest" } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI Gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "AI Gateway group description.", "example": "My AI Gateway group." }, "config": { "type": "object", "description": "Configuration for the AI Gateway group.", "properties": { "image_tag": { "type": "string", "description": "The AISIX (AI Gateway) image tag to deploy.", "example": "latest" } } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}": { "get": { "tags": [ "AI Gateway Group" ], "summary": "Get an AI Gateway group", "operationId": "getAIGatewayGroup", "description": "IAM Action: `ai_gateway:GetAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns the specified AI Gateway group by ID.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successfully retrieved or modified the AI Gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "AI Gateway group description.", "example": "My AI Gateway group." }, "config": { "type": "object", "description": "Configuration for the AI Gateway group.", "properties": { "image_tag": { "type": "string", "description": "The AISIX (AI Gateway) image tag to deploy.", "example": "latest" } } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "AI Gateway Group" ], "summary": "Update an AI Gateway group", "operationId": "updateAIGatewayGroup", "description": "IAM Action: `ai_gateway:UpdateAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nUpdates the name, description, or configuration of the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "AI Gateway group description.", "example": "My AI Gateway group." }, "config": { "type": "object", "description": "Configuration for the AI Gateway group.", "properties": { "image_tag": { "type": "string", "description": "The AISIX (AI Gateway) image tag to deploy.", "example": "latest" } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI Gateway group.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "name": { "description": "The object name.", "type": "string", "minLength": 1, "maxLength": 100, "example": "us-west-rsc" }, "description": { "type": "string", "description": "AI Gateway group description.", "example": "My AI Gateway group." }, "config": { "type": "object", "description": "Configuration for the AI Gateway group.", "properties": { "image_tag": { "type": "string", "description": "The AISIX (AI Gateway) image tag to deploy.", "example": "latest" } } }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 }, "updated_at": { "description": "The object updated timestamp.", "type": "integer", "minimum": 0, "example": 1742288235 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "AI Gateway Group" ], "summary": "Delete an AI Gateway group", "operationId": "deleteAIGatewayGroup", "description": "IAM Action: `ai_gateway:DeleteAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nDeletes the specified AI Gateway group and all its associated instances.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}/instances": { "get": { "tags": [ "AI Gateway Group", "AI Gateway Instance" ], "summary": "List AI Gateway instances in a group", "operationId": "listAIGatewayInstances", "description": "IAM Action: `ai_gateway:GetAIGatewayInstance`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns 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.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successfully retrieved the list of AI Gateway instances.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of AI Gateway instances.", "items": { "type": "object", "description": "A single AISIX data plane instance.", "properties": { "instance_id": { "type": "string", "description": "The unique identifier for the instance.", "example": "aisix-node-001" }, "ai_gateway_group_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "hostname": { "type": "string", "description": "Hostname of the instance.", "example": "aisix-node-001" }, "ip": { "type": "string", "description": "IP address of the instance.", "example": "192.168.1.100" }, "version": { "type": "string", "description": "Version of the AISIX binary.", "example": "1.0.0" }, "ports": { "type": "array", "description": "Ports the instance is listening on.", "items": { "type": "integer" }, "example": [ 9080, 9443 ] }, "last_heartbeat_time": { "type": "string", "format": "date-time", "description": "Timestamp of the last heartbeat received from the instance." }, "status": { "type": "string", "description": "The computed health status of the instance.\n- `Healthy`: last heartbeat was received within 60 seconds.\n- `LostConnection`: last heartbeat was received between 60 seconds and 2 hours ago.\n- `Offline`: no heartbeat received for more than 2 hours.\n", "enum": [ "Healthy", "LostConnection", "Offline" ], "example": "Healthy" }, "created_at": { "description": "The object created timestamp.", "type": "integer", "minimum": 0, "example": 1742288232 } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}/instances/{ai_gateway_instance_id}": { "delete": { "tags": [ "AI Gateway Group", "AI Gateway Instance" ], "summary": "Delete a single AI Gateway instance", "operationId": "deleteAIGatewayInstance", "description": "IAM Action: `ai_gateway:DeleteAIGatewayInstance`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nRemoves the specified AI Gateway instance from its group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "ai_gateway_instance_id", "in": "path", "required": true, "description": "AI Gateway instance ID.", "example": "aisix-node-001", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}/deployment/docker": { "get": { "tags": [ "AI Gateway Group", "AI Gateway Instance" ], "summary": "Generate a Docker run command to install an AI Gateway instance", "operationId": "generateAIInstallScriptForDocker", "description": "IAM Action: `ai_gateway:GetAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nGenerates a `docker run` command that configures and starts an AISIX AI Gateway instance connected to the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "dp_manager_address", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The IP address of the control plane.", "example": "10.15.101.5" } }, { "name": "validity_period", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } }, { "name": "image", "in": "query", "required": false, "description": "Docker image.", "schema": { "type": "string", "minLength": 1 }, "example": "api7/api7-ee-3-gateway" }, { "name": "http_port", "in": "query", "required": false, "description": "The HTTP port of the gateway.", "schema": { "type": "integer", "default": 9080 } }, { "name": "name", "in": "query", "required": false, "description": "The hostname of the gateway.", "schema": { "type": "string", "minLength": 1 } }, { "name": "extra_args[]", "description": "Additional docker run arguments.", "in": "query", "required": false, "style": "form", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "a=b", "c=d" ] } ], "responses": { "200": { "description": "Successfully generated the Docker run command for AI Gateway installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "docker run -d \\\n -e API7_CONTROL_PLANE_ENDPOINTS='[\"https://10.0.0.1:31344\"]' \\\n -e API7_CONTROL_PLANE_CERT=\"-----BEGIN CERTIFICATE-----\n ...\n -----END CERTIFICATE-----\" \\\n -e API7_CONTROL_PLANE_KEY=\"-----BEGIN PRIVATE KEY-----\n ...\n -----END PRIVATE KEY-----\" \\\n -e API7_CONTROL_PLANE_CA=\"-----BEGIN CERTIFICATE-----\n ...\n -----END CERTIFICATE-----\" \\\n -p 3000:3000 \\\n api7/aisix:latest\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}/deployment/docker-compose": { "get": { "tags": [ "AI Gateway Group", "AI Gateway Instance" ], "summary": "Generate a Docker Compose file to install an AI Gateway instance", "operationId": "generateAIInstallScriptForDockerCompose", "description": "IAM Action: `ai_gateway:GetAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nGenerates a Docker Compose configuration that starts an AISIX AI Gateway instance connected to the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "dp_manager_address", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The IP address of the control plane.", "example": "10.15.101.5" } }, { "name": "validity_period", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } }, { "name": "image", "in": "query", "required": false, "description": "Docker image.", "schema": { "type": "string", "minLength": 1 }, "example": "api7/api7-ee-3-gateway" }, { "name": "http_port", "in": "query", "required": false, "description": "The HTTP port of the gateway.", "schema": { "type": "integer", "default": 9080 } }, { "name": "name", "in": "query", "required": false, "description": "The name of the docker compose container and service.", "schema": { "type": "string", "default": "api7-ee-3-gateway", "minLength": 1 } }, { "name": "extra_args[]", "description": "Additional docker run arguments.", "in": "query", "required": false, "style": "form", "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "a=b", "c=d" ] } ], "responses": { "200": { "description": "Successfully generated the Docker Compose configuration for AI Gateway installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "services:\n ai-gateway:\n image: api7/aisix:latest\n container_name: ai-gateway\n restart: always\n ports:\n - \"3000:3000\"\n environment:\n API7_CONTROL_PLANE_ENDPOINTS: '[\"https://10.0.0.1:31344\"]'\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}/deployment/helm/script": { "get": { "tags": [ "AI Gateway Group", "AI Gateway Instance" ], "summary": "Generate a Helm install script for an AI Gateway instance", "operationId": "generateAIInstallScriptForHelm", "description": "IAM Action: `ai_gateway:GetAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nGenerates a shell script that uses Helm to install an AISIX AI Gateway instance in Kubernetes, connected to the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "dp_manager_address", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The IP address of the control plane.", "example": "10.15.101.5" } }, { "name": "validity_period", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } }, { "name": "name", "in": "query", "required": true, "description": "Gateway name.", "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "required": true, "description": "Gateway namespace.", "schema": { "type": "string" } }, { "name": "service_account", "in": "query", "required": false, "description": "Service account to install the gateway.", "schema": { "type": "string" } }, { "name": "replicas", "in": "query", "required": false, "description": "The number of replicas.", "schema": { "type": "integer", "default": 1 } }, { "name": "workers", "in": "query", "required": false, "description": "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.", "example": 5, "schema": { "type": "integer" } }, { "name": "cpu_limit", "in": "query", "required": false, "description": "The CPU limit in number of cores.", "example": "6", "schema": { "type": "string" } }, { "name": "memory_limit", "in": "query", "required": false, "description": "The memory limit. Use the format ``.", "example": "6Gi", "schema": { "type": "string" } }, { "name": "extra_values[]", "in": "query", "description": "Extra values to be passed to the Helm chart, in the form of `key=value`.", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "a=b", "c=d" ] } ], "responses": { "200": { "description": "Successfully generated the Helm install script for AI Gateway installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "helm repo add api7 https://charts.api7.ai\nhelm repo update\nhelm upgrade --install -n default --create-namespace ai-gateway api7/aisix \\\n --set \"extraEnvVars[0].name=API7_CONTROL_PLANE_ENDPOINTS\" \\\n --set-string 'extraEnvVars[0].value=[\"https://10.0.0.1:31344\"]' \\\n --set \"extraEnvVars[1].name=API7_CONTROL_PLANE_CERT\" \\\n --set \"extraEnvVars[1].valueFrom.secretKeyRef.name=ai-gateway-tls\" \\\n --set \"extraEnvVars[1].valueFrom.secretKeyRef.key=tls.crt\" \\\n --set \"extraEnvVars[2].name=API7_CONTROL_PLANE_KEY\" \\\n --set \"extraEnvVars[2].valueFrom.secretKeyRef.name=ai-gateway-tls\" \\\n --set \"extraEnvVars[2].valueFrom.secretKeyRef.key=tls.key\" \\\n --set \"extraEnvVars[3].name=API7_CONTROL_PLANE_CA\" \\\n --set \"extraEnvVars[3].valueFrom.secretKeyRef.name=ai-gateway-tls\" \\\n --set \"extraEnvVars[3].valueFrom.secretKeyRef.key=ca.crt\" \\\n --set \"image.tag=latest\"\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}/deployment/helm/yaml": { "get": { "tags": [ "AI Gateway Group", "AI Gateway Instance" ], "summary": "Generate a Helm values YAML for an AI Gateway instance", "operationId": "generateAIInstallYamlForHelm", "description": "IAM Action: `ai_gateway:GetAIGatewayGroup`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nGenerates a Helm values YAML file for deploying an AISIX AI Gateway instance in Kubernetes, connected to the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "dp_manager_address", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "The IP address of the control plane.", "example": "10.15.101.5" } }, { "name": "validity_period", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10950, "default": 3650, "description": "The validity period of the certificate in days." } }, { "name": "name", "in": "query", "required": true, "description": "Gateway name.", "schema": { "type": "string" } }, { "name": "namespace", "in": "query", "required": true, "description": "Gateway namespace.", "schema": { "type": "string" } }, { "name": "service_account", "in": "query", "required": false, "description": "Service account to install the gateway.", "schema": { "type": "string" } }, { "name": "replicas", "in": "query", "required": false, "description": "The number of replicas.", "schema": { "type": "integer", "default": 1 } }, { "name": "workers", "in": "query", "required": false, "description": "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.", "example": 5, "schema": { "type": "integer" } }, { "name": "cpu_limit", "in": "query", "required": false, "description": "The CPU limit in number of cores.", "example": "6", "schema": { "type": "string" } }, { "name": "memory_limit", "in": "query", "required": false, "description": "The memory limit. Use the format ``.", "example": "6Gi", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully generated the Helm values YAML for AI Gateway installation.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "extraEnvVars:\n- name: API7_CONTROL_PLANE_ENDPOINTS\n value: '[\"https://10.0.0.1:31344\"]'\n- name: API7_CONTROL_PLANE_CERT\n valueFrom:\n secretKeyRef:\n name: ai-gateway-tls\n key: tls.crt\n- name: API7_CONTROL_PLANE_KEY\n valueFrom:\n secretKeyRef:\n name: ai-gateway-tls\n key: tls.key\n- name: API7_CONTROL_PLANE_CA\n valueFrom:\n secretKeyRef:\n name: ai-gateway-tls\n key: ca.crt\nimage:\n tag: latest\n" } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_groups/{ai_gateway_group_id}/dp_client_certificates": { "post": { "tags": [ "AI Gateway Group", "AI Gateway Instance" ], "summary": "Issue an AI data plane certificate", "operationId": "issueAIDataplaneCertificate", "description": "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.", "parameters": [ { "name": "ai_gateway_group_id", "in": "path", "required": true, "description": "AI Gateway group ID.", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Data plane certificate issued successfully.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "properties": { "id": { "description": "Certificate ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "certificate": { "type": "string", "description": "Certificate content.", "example": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n" }, "private_key": { "type": "string", "description": "Private key content.", "example": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n" }, "expiry": { "description": "Expiration of the certificate.", "type": "integer", "minimum": 0, "example": 1742288230 } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/aisix/admin/models": { "get": { "tags": [ "AI Model" ], "summary": "List AI models in a group", "operationId": "listAIModels", "description": "IAM Action: `ai_gateway:ListAIModels`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns all AI model configurations in the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of AI models.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of AI models.", "items": { "type": "object", "description": "LLM model configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique model ID.", "example": "model-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this model belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", "description": "Human-readable name for the model. Used as the model identifier in aisix proxy requests.", "example": "openai/gpt-4o-alias" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Underlying model identifier used by the provider.", "example": "gpt-4o" }, "provider_id": { "type": "string", "description": "ID of the AIProvider entry that supplies credentials for this model. The provider must belong to the same AI Gateway group.", "example": "provider-abc123" }, "timeout": { "type": "integer", "format": "int64", "minimum": 1, "description": "Request timeout in milliseconds.", "example": 30000 }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was last updated." } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "post": { "tags": [ "AI Model" ], "summary": "Create an AI model", "operationId": "createAIModel", "description": "IAM Action: `ai_gateway:CreateAIModel`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nCreates a new AI model configuration in the specified AI Gateway group. The model will be synced to the aisix data plane via etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "model", "provider_id" ], "properties": { "name": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", "description": "Human-readable name for the model. Used as the model identifier in aisix proxy requests.", "example": "my-gpt4o" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Underlying model identifier used by the provider.", "example": "gpt-4o" }, "provider_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "ID of the AIProvider that supplies credentials for this model. The provider must belong to the same AI Gateway group.", "example": "provider-abc123" }, "timeout": { "type": "integer", "format": "int64", "minimum": 0, "description": "Request timeout in milliseconds.", "example": 30000 }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI model.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "LLM model configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique model ID.", "example": "model-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this model belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", "description": "Human-readable name for the model. Used as the model identifier in aisix proxy requests.", "example": "openai/gpt-4o-alias" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Underlying model identifier used by the provider.", "example": "gpt-4o" }, "provider_id": { "type": "string", "description": "ID of the AIProvider entry that supplies credentials for this model. The provider must belong to the same AI Gateway group.", "example": "provider-abc123" }, "timeout": { "type": "integer", "format": "int64", "minimum": 1, "description": "Request timeout in milliseconds.", "example": 30000 }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "409": { "description": "Conflict — A resource with the same unique identifier (e.g., name) already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/aisix/admin/models/{model_id}": { "get": { "tags": [ "AI Model" ], "summary": "Get an AI model", "operationId": "getAIModel", "description": "IAM Action: `ai_gateway:GetAIModel`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns the specified AI model configuration by ID.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "model_id", "in": "path", "required": true, "description": "AI Model ID.", "example": "model-abc123", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successfully retrieved or modified the AI model.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "LLM model configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique model ID.", "example": "model-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this model belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", "description": "Human-readable name for the model. Used as the model identifier in aisix proxy requests.", "example": "openai/gpt-4o-alias" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Underlying model identifier used by the provider.", "example": "gpt-4o" }, "provider_id": { "type": "string", "description": "ID of the AIProvider entry that supplies credentials for this model. The provider must belong to the same AI Gateway group.", "example": "provider-abc123" }, "timeout": { "type": "integer", "format": "int64", "minimum": 1, "description": "Request timeout in milliseconds.", "example": 30000 }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "AI Model" ], "summary": "Update an AI model", "operationId": "updateAIModel", "description": "IAM Action: `ai_gateway:UpdateAIModel`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nUpdates the specified AI model configuration. Changes are synced to the aisix data plane via etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "model_id", "in": "path", "required": true, "description": "AI Model ID.", "example": "model-abc123", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "model", "provider_id" ], "properties": { "name": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", "description": "Human-readable name for the model. Used as the model identifier in aisix proxy requests.", "example": "my-gpt4o" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Underlying model identifier used by the provider.", "example": "gpt-4o" }, "provider_id": { "type": "string", "minLength": 1, "maxLength": 256, "description": "ID of the AIProvider that supplies credentials for this model. The provider must belong to the same AI Gateway group.", "example": "provider-abc123" }, "timeout": { "type": "integer", "format": "int64", "minimum": 0, "description": "Request timeout in milliseconds.", "example": 30000 }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI model.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "LLM model configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique model ID.", "example": "model-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this model belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$", "description": "Human-readable name for the model. Used as the model identifier in aisix proxy requests.", "example": "openai/gpt-4o-alias" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Underlying model identifier used by the provider.", "example": "gpt-4o" }, "provider_id": { "type": "string", "description": "ID of the AIProvider entry that supplies credentials for this model. The provider must belong to the same AI Gateway group.", "example": "provider-abc123" }, "timeout": { "type": "integer", "format": "int64", "minimum": 1, "description": "Request timeout in milliseconds.", "example": 30000 }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the model was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "AI Model" ], "summary": "Delete an AI model", "operationId": "deleteAIModel", "description": "IAM Action: `ai_gateway:DeleteAIModel`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nDeletes the specified AI model configuration and removes it from etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "model_id", "in": "path", "required": true, "description": "AI Model ID.", "example": "model-abc123", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/aisix/admin/apikeys": { "get": { "tags": [ "AI API Key" ], "summary": "List AI API keys in a group", "operationId": "listAIAPIKeys", "description": "IAM Action: `ai_gateway:ListAIAPIKeys`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns all AI API key configurations in the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of AI API keys.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of AI API keys.", "items": { "type": "object", "description": "API key that grants access to aisix proxy endpoints.", "properties": { "id": { "type": "string", "description": "Unique API key ID.", "example": "apikey-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this API key belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "description": "Optional human-readable label for the API key (control-plane only, not written to etcd).", "example": "my-app-key" }, "key": { "type": "string", "description": "The secret key value used for authentication.", "example": "my-secret-key-value" }, "allowed_models": { "type": "array", "description": "List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.", "items": { "type": "string" }, "example": [ "openai/gpt-4o" ] }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was last updated." } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "post": { "tags": [ "AI API Key" ], "summary": "Create an AI API key", "operationId": "createAIAPIKey", "description": "IAM Action: `ai_gateway:CreateAIAPIKey`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nCreates a new AI API key in the specified AI Gateway group. The key will be synced to the aisix data plane via etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "key", "allowed_models" ], "properties": { "name": { "type": "string", "maxLength": 256, "description": "Optional human-readable label for the API key (control-plane only, not written to the data plane).", "example": "my-app-key" }, "key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The secret key value used for authentication.", "example": "my-secret-key-value" }, "allowed_models": { "type": "array", "description": "Required. List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.", "items": { "type": "string" }, "example": [ "openai/gpt-4o" ] }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI API key.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "API key that grants access to aisix proxy endpoints.", "properties": { "id": { "type": "string", "description": "Unique API key ID.", "example": "apikey-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this API key belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "description": "Optional human-readable label for the API key (control-plane only, not written to etcd).", "example": "my-app-key" }, "key": { "type": "string", "description": "The secret key value used for authentication.", "example": "my-secret-key-value" }, "allowed_models": { "type": "array", "description": "List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.", "items": { "type": "string" }, "example": [ "openai/gpt-4o" ] }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "409": { "description": "Conflict — A resource with the same unique identifier (e.g., name) already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/aisix/admin/apikeys/{api_key_id}": { "get": { "tags": [ "AI API Key" ], "summary": "Get an AI API key", "operationId": "getAIAPIKey", "description": "IAM Action: `ai_gateway:GetAIAPIKey`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns the specified AI API key configuration by ID.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "api_key_id", "in": "path", "required": true, "description": "AI API Key ID.", "example": "apikey-abc123", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successfully retrieved or modified the AI API key.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "API key that grants access to aisix proxy endpoints.", "properties": { "id": { "type": "string", "description": "Unique API key ID.", "example": "apikey-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this API key belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "description": "Optional human-readable label for the API key (control-plane only, not written to etcd).", "example": "my-app-key" }, "key": { "type": "string", "description": "The secret key value used for authentication.", "example": "my-secret-key-value" }, "allowed_models": { "type": "array", "description": "List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.", "items": { "type": "string" }, "example": [ "openai/gpt-4o" ] }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "AI API Key" ], "summary": "Update an AI API key", "operationId": "updateAIAPIKey", "description": "IAM Action: `ai_gateway:UpdateAIAPIKey`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nUpdates the specified AI API key configuration. Changes are synced to the aisix data plane via etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "api_key_id", "in": "path", "required": true, "description": "AI API Key ID.", "example": "apikey-abc123", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "key", "allowed_models" ], "properties": { "name": { "type": "string", "maxLength": 256, "description": "Optional human-readable label for the API key (control-plane only, not written to the data plane).", "example": "my-app-key" }, "key": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The secret key value used for authentication.", "example": "my-secret-key-value" }, "allowed_models": { "type": "array", "description": "Required. List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.", "items": { "type": "string" }, "example": [ "openai/gpt-4o" ] }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI API key.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "API key that grants access to aisix proxy endpoints.", "properties": { "id": { "type": "string", "description": "Unique API key ID.", "example": "apikey-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this API key belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "description": "Optional human-readable label for the API key (control-plane only, not written to etcd).", "example": "my-app-key" }, "key": { "type": "string", "description": "The secret key value used for authentication.", "example": "my-secret-key-value" }, "allowed_models": { "type": "array", "description": "List of model names this key is permitted to access (strict whitelist). An empty array means the key cannot access any model.", "items": { "type": "string" }, "example": [ "openai/gpt-4o" ] }, "rate_limit": { "type": "object", "description": "Rate limit configuration for AI requests. Field names use the abbreviated forms that match aisix's internal representation (tpm/tpd/rpm/rpd/concurrency).", "properties": { "tpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per minute (token_per_minute)." }, "tpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum tokens allowed per day (token_per_day)." }, "rpm": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per minute (request_per_minute)." }, "rpd": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum requests allowed per day (request_per_day)." }, "concurrency": { "type": "integer", "format": "int64", "minimum": 1, "description": "Maximum concurrent requests allowed." } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the API key was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "AI API Key" ], "summary": "Delete an AI API key", "operationId": "deleteAIAPIKey", "description": "IAM Action: `ai_gateway:DeleteAIAPIKey`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nDeletes the specified AI API key configuration and removes it from etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "api_key_id", "in": "path", "required": true, "description": "AI API Key ID.", "example": "apikey-abc123", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/aisix/admin/providers": { "get": { "tags": [ "AI Provider" ], "summary": "List AI providers in a group", "operationId": "listAIProviders", "description": "IAM Action: `ai_gateway:ListAIProviders`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns all AI provider configurations in the specified AI Gateway group.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Order to list the resources by. The sorting index follows the configuration of `order_by`.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of AI providers.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating a list of resources.", "properties": { "list": { "type": "array", "description": "An array of resources.", "items": { "type": "object" } }, "total": { "type": "integer", "minimum": 0, "example": 1, "description": "Total number of objects." } } }, { "type": "object", "properties": { "list": { "type": "array", "description": "An array of AI providers.", "items": { "type": "object", "description": "LLM provider configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique provider ID.", "example": "provider-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this provider belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "description": "Human-readable name for the provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "Provider type. Determines the shape of the config object.", "enum": [ "openai", "anthropic", "azure", "bedrock", "deepseek", "gemini", "openrouter" ], "example": "openai" }, "config": { "type": "object", "description": "Provider-specific credentials and configuration. The required fields depend on the provider type. See the request schemas for details.\n", "example": { "api_key": "sk-..." } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was last updated." } } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "post": { "tags": [ "AI Provider" ], "summary": "Create an AI provider", "operationId": "createAIProvider", "description": "IAM Action: `ai_gateway:CreateAIProvider`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nCreates a new AI provider configuration in the specified AI Gateway group. The provider will be synced to the aisix data plane via etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "type", "config" ], "properties": { "name": { "type": "string", "maxLength": 256, "description": "Human-readable name for the provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "Provider type. Determines the shape of the config object.", "enum": [ "openai", "anthropic", "azure", "bedrock", "deepseek", "gemini", "openrouter" ], "example": "openai" }, "config": { "type": "object", "description": "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? }\n" } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI provider.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "LLM provider configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique provider ID.", "example": "provider-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this provider belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "description": "Human-readable name for the provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "Provider type. Determines the shape of the config object.", "enum": [ "openai", "anthropic", "azure", "bedrock", "deepseek", "gemini", "openrouter" ], "example": "openai" }, "config": { "type": "object", "description": "Provider-specific credentials and configuration. The required fields depend on the provider type. See the request schemas for details.\n", "example": { "api_key": "sk-..." } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "409": { "description": "Conflict — A resource with the same unique identifier (e.g., name) already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/aisix/admin/providers/{provider_id}": { "get": { "tags": [ "AI Provider" ], "summary": "Get an AI provider", "operationId": "getAIProvider", "description": "IAM Action: `ai_gateway:GetAIProvider`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nReturns the specified AI provider configuration by ID.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "provider_id", "in": "path", "required": true, "description": "AI Provider ID.", "example": "provider-abc123", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successfully retrieved or modified the AI provider.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "LLM provider configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique provider ID.", "example": "provider-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this provider belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "description": "Human-readable name for the provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "Provider type. Determines the shape of the config object.", "enum": [ "openai", "anthropic", "azure", "bedrock", "deepseek", "gemini", "openrouter" ], "example": "openai" }, "config": { "type": "object", "description": "Provider-specific credentials and configuration. The required fields depend on the provider type. See the request schemas for details.\n", "example": { "api_key": "sk-..." } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "put": { "tags": [ "AI Provider" ], "summary": "Update an AI provider", "operationId": "updateAIProvider", "description": "IAM Action: `ai_gateway:UpdateAIProvider`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nUpdates the specified AI provider configuration. Changes are synced to the aisix data plane via etcd.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "provider_id", "in": "path", "required": true, "description": "AI Provider ID.", "example": "provider-abc123", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "type", "config" ], "properties": { "name": { "type": "string", "maxLength": 256, "description": "Human-readable name for the provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "Provider type. Determines the shape of the config object.", "enum": [ "openai", "anthropic", "azure", "bedrock", "deepseek", "gemini", "openrouter" ], "example": "openai" }, "config": { "type": "object", "description": "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? }\n" } } } } } }, "responses": { "200": { "description": "Successfully retrieved or modified the AI provider.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "The outer structure for encapsulating the specific resource.", "properties": { "value": { "type": "object", "description": "The specific resource." } } }, { "type": "object", "properties": { "value": { "type": "object", "description": "LLM provider configuration in an AI Gateway group.", "properties": { "id": { "type": "string", "description": "Unique provider ID.", "example": "provider-abc123" }, "ai_gateway_group_id": { "type": "string", "description": "ID of the AI Gateway group this provider belongs to (control-plane only).", "example": "group-abc123" }, "name": { "type": "string", "maxLength": 256, "description": "Human-readable name for the provider.", "example": "my-openai-provider" }, "type": { "type": "string", "description": "Provider type. Determines the shape of the config object.", "enum": [ "openai", "anthropic", "azure", "bedrock", "deepseek", "gemini", "openrouter" ], "example": "openai" }, "config": { "type": "object", "description": "Provider-specific credentials and configuration. The required fields depend on the provider type. See the request schemas for details.\n", "example": { "api_key": "sk-..." } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the provider was last updated." } } } } } ] } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } }, "delete": { "tags": [ "AI Provider" ], "summary": "Delete an AI provider", "operationId": "deleteAIProvider", "description": "IAM Action: `ai_gateway:DeleteAIProvider`, Resource: `arn:api7:ai_gateway:aigatewaygroup/%s`\nDeletes the specified AI provider configuration and removes it from etcd. Returns 409 Conflict if any AI models reference this provider.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "required": true, "description": "AI Gateway group ID (filter resources by group).", "example": "abc1234567890", "schema": { "type": "string", "minLength": 1 } }, { "name": "provider_id", "in": "path", "required": true, "description": "AI Provider ID.", "example": "provider-abc123", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Operation completed successfully with no response body.", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "404": { "description": "Not Found — The requested resource does not exist or has been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } }, "409": { "description": "Conflict — A resource with the same unique identifier (e.g., name) already exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } }, "/api/ai_gateway_logs": { "get": { "tags": [ "AI Gateway Log" ], "summary": "List AI gateway span logs", "operationId": "listAIGatewayLogs", "description": "IAM Action: `ai_gateway:ListAIGatewayLogs`, Resource: `arn:api7:ai_gateway:aigatewaygroup/*`\nReturns a paginated list of AI/LLM span logs extracted from OTLP traces sent by AI gateway dataplanes.", "parameters": [ { "name": "ai_gateway_group_id", "in": "query", "description": "Filter logs by AI gateway group ID.", "required": false, "schema": { "type": "string" } }, { "name": "instance_id", "in": "query", "description": "Filter logs by dataplane instance ID.", "required": false, "schema": { "type": "string" } }, { "name": "model", "in": "query", "description": "Filter logs by model name.", "required": false, "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "Filter logs with start_time >= this value (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "Filter logs with start_time < this value (RFC3339 format).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" }, { "name": "page_size", "schema": { "type": "integer", "format": "int32", "minimum": 1 }, "description": "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.", "in": "query" } ], "responses": { "200": { "description": "A paginated list of AI gateway span logs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique log record ID (hex traceID + spanID)." }, "instance_id": { "type": "string", "description": "Dataplane instance ID from resource attribute service.instance.id." }, "ai_gateway_group_id": { "type": "string", "description": "AI gateway group ID." }, "trace_id": { "type": "string", "description": "OTLP trace ID (hex-encoded)." }, "span_id": { "type": "string", "description": "OTLP span ID (hex-encoded)." }, "key_id": { "type": "string", "description": "API key ID used for this request (aisix.apikey_id attribute)." }, "model": { "type": "string", "description": "LLM model name (gen_ai.request.model or gen_ai.response.model)." }, "input_tokens": { "type": "integer", "description": "Number of input tokens (gen_ai.usage.input_tokens)." }, "output_tokens": { "type": "integer", "description": "Number of output tokens (gen_ai.usage.output_tokens)." }, "cache_read_tokens": { "type": "integer", "description": "Number of cache-read input tokens." }, "cache_write_tokens": { "type": "integer", "description": "Number of cache-creation input tokens." }, "duration_ms": { "type": "integer", "description": "Total request duration in milliseconds." }, "status_code": { "type": "integer", "description": "HTTP status code of the LLM response." }, "start_time": { "type": "string", "format": "date-time", "description": "Request start time (span StartTimeUnixNano)." }, "first_response_at": { "type": "string", "format": "date-time", "description": "Time of first response token, derived from the first-token-arrived span event (\"first token arrived\" / kind=first_token_arrived)." }, "created_at": { "type": "string", "format": "date-time", "description": "Record creation timestamp." } } } }, "total": { "type": "integer", "description": "Total number of matching log records." } } } } } }, "400": { "description": "Bad Request — The request was malformed or contained invalid parameters. Check the error_msg field for details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "object", "description": "The specific resource.", "example": {} }, "error_msg": { "type": "string", "description": "The error message.", "example": "error message" } } } } } } } } } }, "components": { "schemas": { "HTTPService": { "type": "object", "required": [ "name" ], "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "type": { "type": "string", "description": "Type of service. `http` corresponds to L7 service and `stream` corresponds to L4 service.", "enum": [ "http", "stream" ], "default": "http" }, "hosts": { "type": "array", "description": "The hosts of the service to accept incoming requests.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "path_prefix": { "maxLength": 4096, "minLength": 1, "pattern": "^/", "type": "string", "description": "The listening path prefix of the service.", "example": "/test" }, "strip_path_prefix": { "type": "boolean", "default": true, "description": "If true, strip the path prefix when proxying the request to the upstream." }, "upstream": { "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] } } }, "StreamService": { "type": "object", "required": [ "name" ], "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } }, "type": { "type": "string", "description": "Type of service. `stream` corresponds to L4 service.", "enum": [ "stream" ] }, "upstream": { "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } } } }, "HTTPUpstream": { "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, "StreamUpstream": { "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } }, "HTTPRoute": { "description": "The route description.", "type": "object", "required": [ "name", "paths" ], "allOf": [ { "type": "object", "properties": { "name": { "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "methods": { "description": "The allowed HTTP methods to access the route. If empty, all HTTP methods are allowed.", "type": "array", "uniqueItems": true, "minItems": 1, "maxItems": 9, "items": { "type": "string", "description": "The API (HTTP) method.", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE" ] } }, "vars": { "description": "Conditions in the format of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions) to match requests to routes. Case sensitive when matching a cookie name.", "type": "array", "example": [ [ "arg_version", "==", "v2" ], [ "arg_ttl", "<", 3600 ] ], "items": {} }, "paths": { "maxItems": 64, "minItems": 1, "type": "array", "description": "The URL path(s) (after the service's `path_prefix`) that the route will listen to. Each path should start with a `/`.", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "example": "/get" } }, "priority": { "type": "integer", "default": 0, "description": "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": { "type": "boolean", "description": "If true, enable Websocket proxying for the route.", "nullable": true } } }, { "type": "object", "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } } ] }, "HTTPServiceRuntimeConfiguration": { "type": "object", "minProperties": 1, "properties": { "hosts": { "type": "array", "description": "The hosts of the service to accept incoming requests.", "uniqueItems": true, "minItems": 1, "maxItems": 32, "items": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" } }, "path_prefix": { "maxLength": 4096, "minLength": 1, "pattern": "^/", "type": "string", "description": "The listening path prefix of the service.", "example": "/test" }, "strip_path_prefix": { "type": "boolean", "default": true, "description": "If true, strip the path prefix when proxying the request to the upstream." }, "upstream": { "description": "The upstream contains necessary information for the gateway to proxy\nrequest to the backend service.\n", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The upstream name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `http`.", "type": "string", "enum": [ "http", "https", "grpc", "grpcs" ], "default": "http" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "default": "roundrobin", "description": "Load balancing algorithm to distribute traffic.", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream.", "minimum": 0, "maximum": 65535, "type": "integer", "example": 50 }, "keepalive_pool": { "description": "Upstream keepalive connection pool.", "type": "object", "properties": { "size": { "description": "The number of idle keepalive connections per worker to upstream servers.", "minimum": 1, "type": "integer", "default": 320 }, "idle_timeout": { "description": "Time an idle keepalive connection remains open before being closed, in seconds.", "minimum": 0, "type": "number", "format": "float", "default": 60 }, "requests": { "description": "The number of requests a single keepalive connection can handle before closing.", "minimum": 1, "type": "integer", "default": 1000 } } }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "pass_host": { "type": "string", "description": "The approach to decide the host header before forwarding requests to an upstream.\n* `pass` uses the host specified in the service.\n* `node` uses the host specified in the upstream.\n* `rewrite` uses custom host.", "enum": [ "pass", "node", "rewrite" ], "default": "pass" }, "upstream_host": { "description": "Value to rewrite the host header to. Only used if `pass_host` is `rewrite`.", "type": "string", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "nodes": { "type": "array", "description": "The upstream endpoints.", "example": [ { "host": "httpbin.org", "port": 8080, "weight": 100 } ], "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "service_name": { "description": "Service name in the service registry. Only valid for service discovery.", "type": "string", "minLength": 1, "maxLength": 256, "example": "/public/group/httpbin" }, "discovery_type": { "type": "string", "description": "Type of service discovery. Only valid for service discovery.", "enum": [ "kubernetes", "nacos", "consul" ], "example": "nacos" }, "discovery_args": { "description": "Service discovery arguments. Only valid for service discovery.", "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "namespace_id": "public", "group_name": "DEFAULT_GROUP" } } } }, "tls": { "deprecated": true, "description": "Replace with `client_certificate` and `ca_certificates`", "oneOf": [ { "properties": { "client_cert": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The certificate in PEM format.", "example": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" }, "client_key": { "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\$]", "description": "The private key in PEM format.", "example": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" } }, "required": [ "client_cert", "client_key" ] }, { "properties": { "client_cert_id": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "required": [ "client_cert_id" ] } ] }, "client_certificate": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" }, "ca_certificates": { "type": "array", "description": "CA certificates.", "items": { "description": "The object ID.", "type": "string", "pattern": "^[a-zA-Z0-9-_.]+$", "minLength": 1, "maxLength": 256, "example": "bd58fce2-b6cc-4d2d-a53c-6ce11b19c101" } }, "tls_verify": { "type": "boolean", "description": "If true, verify TLS." }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } }, "oneOf": [ { "title": "Use Upstream Nodes", "required": [ "nodes" ] }, { "title": "Use Service Registry", "required": [ "service_name", "discovery_type" ] } ] }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, "StreamServiceRuntimeConfiguration": { "type": "object", "minProperties": 1, "properties": { "upstream": { "description": "Upstream configurations.", "type": "object", "properties": { "name": { "default": "default", "maxLength": 65536, "description": "The object name.", "type": "string", "minLength": 1, "example": "us-west-rsc" }, "scheme": { "description": "The protocol that is used for communicating with the backend service when the service type is `stream`.", "type": "string", "enum": [ "tcp", "udp" ], "default": "tcp" }, "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } }, "type": { "type": "string", "description": "Load balancing algorithm to distribute traffic.", "default": "roundrobin", "example": "chash", "enum": [ "chash", "roundrobin", "least_conn", "ewma" ] }, "hash_on": { "description": "Type of value to hash on when `type` is `chash`.", "type": "string", "enum": [ "vars", "header", "cookie", "consumer", "vars_combinations" ], "default": "vars" }, "key": { "type": "string", "minLength": 1, "description": "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](https://docs.api7.ai/enterprise/reference/built-in-variables). - When `hash_on` is set to `vars_combinations`, `key` is required and supports a combination of [built-in variables](https://docs.api7.ai/enterprise/reference/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.", "example": "$host" }, "retries": { "description": "The number of retries while passing the request to an upstream using the underlying Nginx mechanism.", "minimum": 0, "maximum": 65535, "type": "integer" }, "retry_timeout": { "description": "Timeout to continue with retries. Setting this to 0 disables the retry timeout.", "type": "number", "format": "float", "minimum": 0, "default": 0 }, "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "nodes": { "type": "array", "description": "The upstream endpoints.", "items": { "description": "The definition for an upstream endpoint.", "required": [ "host", "port", "weight" ], "type": "object", "properties": { "host": { "description": "Upstream host.", "pattern": "^\\*?[0-9a-zA-Z-._\\[\\]:]+$", "type": "string", "example": "httpbin.org" }, "port": { "description": "Upstream port.", "maximum": 65535, "minimum": 1, "type": "integer", "example": 8080 }, "weight": { "description": "Upstream weight.", "maximum": 65535, "minimum": 0, "type": "integer", "example": 100 }, "priority": { "description": "Node priority. A higher value corresponds to a higher priority.", "type": "integer", "default": 0 } } } }, "checks": { "type": "object", "description": "Health check configurations.", "anyOf": [ { "title": "Active Check", "type": "object", "required": [ "active" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } } } }, { "title": "Passive Check", "type": "object", "required": [ "active", "passive" ], "properties": { "active": { "type": "object", "description": "Active health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "timeout": { "type": "number", "format": "float", "default": 1, "description": "Active check timeout in seconds." }, "concurrency": { "type": "integer", "format": "int32", "default": 10, "description": "The number of targets to be checked at the same time during the active check." }, "host": { "type": "string", "description": "The HTTP host.", "pattern": "^\\*?[0-9a-zA-Z-._]+$", "example": "httpbin.org" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535, "format": "int32", "description": "By default, the port is the same as the one defined in the upstream target." }, "http_path": { "type": "string", "default": "/", "description": "The HTTP path in HTTP probe requests." }, "https_verify_certificate": { "type": "boolean", "description": "Whether to verify the target's TLS certificate.", "default": true }, "req_headers": { "type": "array", "description": "The request headers.", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "example": "user-agent: go/1.20" } }, "healthy": { "type": "object", "description": "Active health check healthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking healthy targets in seconds." }, "http_statuses": { "default": [ 200, 302 ], "type": "array", "minItems": 1, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 1, "type": "integer", "default": 2, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Active health check unhealthy configurations.", "properties": { "interval": { "default": 1, "minimum": 1, "type": "integer", "format": "int32", "description": "Time interval of checking unhealthy targets in seconds." }, "http_statuses": { "type": "array", "default": [ 429, 404, 500, 501, 502, 503, 504, 505 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "http_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." }, "tcp_failures": { "minimum": 1, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 1, "maximum": 254, "default": 3, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." } } } } }, "passive": { "type": "object", "description": "Passive health check configurations.", "properties": { "type": { "type": "string", "enum": [ "http", "https", "tcp" ], "default": "http", "description": "Active check probing type." }, "healthy": { "type": "object", "description": "Passive health check healthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered healthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "successes": { "minimum": 0, "type": "integer", "default": 5, "format": "int32", "description": "The number of successful probes to define a healthy target." } } }, "unhealthy": { "type": "object", "description": "Passive health check unhealthy configurations.", "properties": { "http_statuses": { "type": "array", "default": [ 429, 500, 503 ], "minItems": 1, "uniqueItems": true, "description": "A list of HTTP response status codes which are considered unhealthy.", "items": { "minimum": 200, "maximum": 599, "type": "integer" } }, "tcp_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 2, "format": "int32", "description": "The number of TCP-related failures to define an unhealthy target." }, "timeouts": { "minimum": 0, "maximum": 254, "default": 7, "type": "integer", "format": "int32", "description": "The number of probe timeouts to define an unhealthy target." }, "http_failures": { "minimum": 0, "maximum": 254, "type": "integer", "default": 5, "format": "int32", "description": "The number of HTTP-related failures to define an unhealthy target." } } } } } } } ] } } }, "status": { "description": "The object status. 1 means the object is active while 0 means it's inactive.\n", "type": "integer", "enum": [ 0, 1 ] }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, "RouteRuntimeConfiguration": { "type": "object", "additionalProperties": false, "properties": { "timeout": { "description": "Timeout settings for connecting to, sending, and receiving messages from the upstream, in seconds.", "type": "object", "properties": { "connect": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Connection timeout in seconds." }, "send": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Sending timeout in seconds." }, "read": { "minimum": 0, "exclusiveMinimum": true, "type": "integer", "default": 60, "description": "Receiving timeout in seconds." } } }, "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, "StreamRouteRuntimeConfiguration": { "type": "object", "additionalProperties": false, "properties": { "plugins": { "description": "Key-value pairs of plugins and their configurations on the object.", "type": "object", "example": { "key-auth": {} } } } }, "VaultSecret": { "allOf": [ { "title": "Vault", "description": "HashiCorp Vault configurations when Vault is the secret provider.", "type": "object", "required": [ "uri", "prefix", "token" ], "properties": { "uri": { "description": "Vault endpoint.", "example": "http://10.42.17.8:8200", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "prefix": { "type": "string", "description": "Vault prefix to access secrets.", "example": "kv/apisix" }, "token": { "type": "string", "description": "Vault token.", "example": "apisix-quickstart-vault-token" }, "namespace": { "type": "string", "description": "Vault namespace.", "example": "apisix" }, "kv_version": { "type": "string", "description": "Vault KV secrets engine version.", "enum": [ "kv-v1" ], "default": "kv-v1" }, "authentication_method": { "type": "string", "description": "Authentication method.", "enum": [ "token" ], "default": "token" } } }, { "type": "object", "properties": { "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] }, "AWSSecret": { "allOf": [ { "title": "AWS Secret", "description": "AWS Secret configurations when AWS Secret is the secret provider.", "type": "object", "required": [ "access_key_id", "secret_access_key" ], "properties": { "access_key_id": { "description": "AWS access key ID.", "type": "string" }, "secret_access_key": { "description": "AWS secret access key.", "type": "string" }, "session_token": { "description": "AWS session token.", "type": "string" }, "region": { "type": "string", "description": "AWS region.", "default": "us-east-1" }, "endpoint_url": { "description": "AWS endpoint.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" } } }, { "type": "object", "properties": { "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] }, "KubernetesSecret": { "allOf": [ { "type": "object", "description": "Kubernetes Secret configurations when Kubernetes Secret is the secret provider.", "properties": { "apiserver_addr": { "description": "Kubernetes API server Address.", "type": "string", "pattern": "^[^/]+://([\\da-zA-Z.-]+|\\[[\\da-fA-F:]+\\])(:\\d+)?" }, "token": { "description": "Service account token for Kubernetes API authentication", "type": "string", "minLength": 1 }, "token_file": { "description": "The path to the token file of the Kubernetes service account.", "type": "string", "minLength": 1 } }, "oneOf": [ { "title": "Kubernetes Secret (Token)", "required": [ "apiserver_addr", "token" ] }, { "title": "Kubernetes Secret (Token File)", "required": [ "apiserver_addr", "token_file" ] } ] }, { "type": "object", "properties": { "desc": { "description": "The object description.", "type": "string", "maxLength": 65536, "example": "Object description." }, "labels": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^.+$", "minLength": 1, "maxLength": 65536 }, "description": "Key-value pairs of labels.", "example": { "version": "v2", "env": "prod" } } } } ] } }, "securitySchemes": { "APIKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" }, "BasicAuth": { "type": "http", "scheme": "basic" } } } }