{"displayName":"Reading List API","version":"v1.0","context":"/reading-list/$version","upstreamDefinitions":[{"name":"my-upstream-1","basePath":"/api/v2","timeout":{"connect":"5s"},"upstreams":[{"url":"http://prod-backend-1:5000","weight":80}]}],"upstream":{"main":{"url":"http://prod-backend:5000/api/v2","ref":"string","hostRewrite":"auto"},"sandbox":{"url":"http://prod-backend:5000/api/v2","ref":"string","hostRewrite":"auto"}},"vhosts":{"main":"api.example.com;docs.example.com;*.example.com","sandbox":"sandbox-api.example.com"},"subscriptionPlans":["Gold","Silver"],"policies":[{"name":"cors","version":"v1","executionCondition":"request.metadata[authenticated] != true","params":{}}],"resilience":{"timeout":"15s","idleTimeout":"0s"},"operations":[{"method":"GET","path":"/books/{id}","match":{"method":"GET","path":{"value":"/books/{id}","type":"Exact"},"headers":[{"name":"version","value":"one","type":"Exact"}]},"policies":[{"name":"cors","version":"v1","executionCondition":"request.metadata[authenticated] != true","params":{}}],"resilience":{"timeout":"15s","idleTimeout":"0s"}}],"deploymentState":"deployed"}
Properties
Name
Type
Required
Restrictions
Description
displayName
string
true
none
Human-readable API name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
version
string
true
none
Semantic version of the API
context
string
true
none
Base path for all API routes (must start with /, no trailing slash). Use version to embed the version in the path (e.g., /reading-list/version resolves to /reading-list/v1.0).
Upstream backend configuration (single target or reference)
vhosts
object
false
none
Custom virtual hosts/domains for the API
main
string
true
none
Custom virtual host(s)/domain(s) for production traffic. One or more hostnames separated by ';' — each hostname serves the main upstream (e.g. when a Gateway API HTTPRoute attaches to multiple listener hostnames). The first entry is the primary vhost. Each hostname may be a wildcard such as *.example.com.
sandbox
string
false
none
Custom virtual host/domain for sandbox traffic
subscriptionPlans
[string]
false
none
List of subscription plan names available for this API
Backend/route timeout configuration. Maps to Envoy RouteAction timeouts. Can be set at the API level (applies to all routes) and/or the operation level (applies to that operation's route). When set at both levels, the operation-level value takes precedence. When unset, the gateway's global route timeout defaults apply.
Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the API is removed from router traffic but configuration, API keys, and policies are preserved for potential redeployment.
Reusable upstream configuration with optional timeout and load balancing settings
Properties
Name
Type
Required
Restrictions
Description
name
string
true
none
Unique identifier for this upstream definition
basePath
string
false
none
Base path prefix for all endpoints in this upstream (e.g., /api/v2). All requests to this upstream will have this path prepended. Must start with '/' and must not end with '/'; omit for root.
List of backend targets with optional weights for load balancing
url
string(uri)
true
none
Backend URL (host and port only, path comes from basePath)
weight
integer
false
none
Relative weight for load balancing across multiple upstream targets. Reserved for future multi-target load balancing; not applied yet (only the first target is currently used).
Backend/route timeout configuration. Maps to Envoy RouteAction timeouts. Can be set at the API level (applies to all routes) and/or the operation level (applies to that operation's route). When set at both levels, the operation-level value takes precedence. When unset, the gateway's global route timeout defaults apply.
Properties
Name
Type
Required
Restrictions
Description
timeout
string
false
none
Maximum time for the entire route (request to upstream response). "0s" disables the timeout.
idleTimeout
string
false
none
Per-route stream idle timeout (overrides the listener stream idle timeout for this route). "0s" disables the timeout.
Upstream backend configuration (single target or reference)
Properties
Name
Type
Required
Restrictions
Description
url
string(uri)
false
none
Direct backend URL to route traffic to
ref
string
false
none
Reference to a predefined upstreamDefinition
hostRewrite
string
false
none
Controls how the Host header is handled when routing to the upstream. auto delegates host rewriting to Envoy, which rewrites the Host header using the upstream cluster host. manual disables automatic rewriting and expects explicit configuration.
An operation is matched either by the simple top-level method+path form, or by the richer 'match' block (method + path + headers). When 'match' is present it is authoritative and the top-level method/path are ignored. At least one form must be provided.
Backend/route timeout configuration. Maps to Envoy RouteAction timeouts. Can be set at the API level (applies to all routes) and/or the operation level (applies to that operation's route). When set at both levels, the operation-level value takes precedence. When unset, the gateway's global route timeout defaults apply.
Version of the policy. Only major-only version is allowed (e.g., v0, v1). Full semantic version (e.g., v1.0.0) is not accepted and will be rejected. The Gateway Controller resolves the major version to the single matching full version installed in the gateway image.
executionCondition
string
false
none
Expression controlling conditional execution of the policy
params
object
false
none
Arbitrary parameters for the policy (free-form key/value structure)
Identifier of the API key. If not provided, a default identifier will be generated
apiKey
string
false
none
Optional plain-text API key value for external key injection. If provided, this key will be used instead of generating a new one. The key will be hashed before storage. The key can be in any format (minimum 36 characters). Use this for injecting externally generated API keys.
maskedApiKey
string
false
none
Masked version of the API key for display purposes. Provided by the platform API when injecting pre-hashed keys.
expiresIn
object
false
none
Expiration duration for the API key
unit
string
true
none
Time unit for expiration
duration
integer
true
none
Duration value for expiration
expiresAt
string(date-time)
false
none
Expiration timestamp. If both expiresIn and expiresAt are provided, expiresAt takes precedence.
externalRefId
string
false
none
External reference ID for the API key. This field is optional and used for tracing purposes only. The gateway generates its own internal ID for tracking.
issuer
string
false
none
Identifies the portal that created this key. If provided, only api keys generated from the same portal will be accepted. If not provided, there is no portal restriction.
{"name":"my-production-key","displayName":"My Production Key","apiKey":"apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","apiId":"reading-list-api-v1.0","status":"active","createdAt":"2026-04-01T10:30:00Z","createdBy":"admin","expiresAt":null,"source":"local"}
Details of an API key
Properties
Name
Type
Required
Restrictions
Description
name
string
true
none
URL-safe identifier for the API key (auto-generated from displayName, immutable, used as path parameter)
displayName
string
false
none
Human-readable name for the API key (user-provided, mutable)
apiKey
string
false
none
Generated API key with apip_ prefix
apiId
string
true
none
Unique public identifier of the API that the key is associated with
Virtual host name used for routing. Supports standard domain names, subdomains, or wildcard domains. Must follow RFC-compliant hostname rules. Wildcards are only allowed in the left-most label (e.g., *.example.com).
Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the MCP Proxy is removed from router traffic but configuration and policies are preserved for potential redeployment.
API-level backend/route timeout configuration. Applies to the traffic-forwarding routes generated for this MCP proxy (GET/POST/DELETE on the MCP resource path). Supported at the API level only. Because MCP transports are long-lived streams, the route timeout defaults to disabled ("0s") for MCP unless a timeout is set here (unlike REST/LLM, which fall back to the gateway's global route timeout); the idle timeout remains the liveness guard.
{"status":"error","message":"Configuration validation failed","errors":[{"field":"spec.context","message":"Context must start with / and cannot end with /"}]}
Stable family-grouping identifier shared by every version of this template. Multiple versions with the same groupId but different handles are surfaced as versions of one template. Defaults to metadata.name when omitted.
managedBy
string
false
none
Origin of the template. Built-in templates use 'wso2'; custom templates default to 'customer' and may be set to any value.
version
string
false
none
Template content version (e.g. v1.0). Multiple versions of the same groupId can coexist; defaults to v1.0 when omitted.
Base path for all API routes (must start with /, no trailing slash)
vhost
string
false
none
Virtual host name used for routing. Supports standard domain names, subdomains, or wildcard domains. Must follow RFC-compliant hostname rules. Wildcards are only allowed in the left-most label (e.g., *.example.com).
DEPRECATED - use operationPolicies. Still honoured (treated identically to operationPolicies).
deploymentState
string
false
none
Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the LLM Provider is removed from router traffic but configuration and policies are preserved for potential redeployment.
API-level backend/route timeout configuration. Applies to all routes generated for this LLM Provider (the routes that forward traffic upstream). Supported at the API level only - LLM routes are synthesized by the gateway, so there is no operation-level override.
Upstream credential. Write-only: accepted on create/update and never returned by the management API on a read, for any role. Supply either a literal value or a secret reference (e.g. a secret template expression); either way the field is omitted from management API response bodies. An update that omits it inherits the stored value; set type: none to remove auth.
Upstream credential. Write-only: accepted on create/update and never returned by the management API on a read, for any role. An update that omits it inherits the stored value; set type: none to remove auth.
Additional LLM provider attached to this proxy as a selectable upstream. Policies route to it by referring to the as name (defaults to id). Optional auth config is used by the proxy when calling a protected LlmProvider over the internal loopback route.
Properties
Name
Type
Required
Restrictions
Description
id
string
true
none
Unique id of a deployed llm provider
as
string
false
none
Logical LLM Provider name used by policies to select this provider. Must be unique within the proxy. Defaults to id when omitted.
Request/response translator applied when this provider is the selected upstream. The proxy injects the translator as a conditional policy whose execution condition matches this provider, so it runs only when the provider is selected. The provider's as name (defaults to id) is passed to the translator as its target upstream.
Request/response translator applied when this provider is the selected upstream. The proxy injects the translator as a conditional policy whose execution condition matches this provider, so it runs only when the provider is selected. The provider's as name (defaults to id) is passed to the translator as its target upstream.
Properties
Name
Type
Required
Restrictions
Description
type
string
true
none
Translator policy name (for example openai-to-anthropic).
version
string
true
none
Major-only translator policy version (for example v1). The Gateway Controller resolves it to the installed full version.
params
object
false
none
Translator-specific parameters (for example model, apiVersion).
Human-readable LLM proxy name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
version
string
true
none
Semantic version of the LLM proxy
context
string
false
none
Base path for all API routes (must start with /, no trailing slash)
vhost
string
false
none
Virtual host name used for routing. Supports standard domain names, subdomains, or wildcard domains. Must follow RFC-compliant hostname rules. Wildcards are only allowed in the left-most label (e.g., *.example.com).
Optional list of additional LLM providers attached to this proxy as selectable upstreams. Policies (e.g. an OpenAI translator) can route requests to any of these by setting the upstream name. The primary provider field above remains the default upstream and the FK target.
DEPRECATED - use operationPolicies. Still honoured (treated identically to operationPolicies).
deploymentState
string
false
none
Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the LLM Proxy is removed from router traffic but configuration and policies are preserved for potential redeployment.
API-level backend/route timeout configuration. Applies to all routes generated for this LLM Proxy (the routes that forward traffic upstream). Supported at the API level only - LLM routes are synthesized by the gateway, so there is no operation-level override.
{"apiVersion":"gateway.api-platform.wso2.com/v1","kind":"Secret","metadata":{"name":"database-password"},"spec":{"displayName":"Database Password","description":"PostgreSQL main database password","value":"sup3rs3cr3t!"}}
{"apiVersion":"gateway.api-platform.wso2.com/v1","kind":"Secret","metadata":{"name":"database-password"},"spec":{"displayName":"Database Password","description":"PostgreSQL main database password","value":"sup3rs3cr3t!"},"status":{"id":"database-password","createdAt":"2026-04-24T07:21:13Z","updatedAt":"2026-04-24T07:21:13Z"}}
Composite of request fields plus a generic k8s-style status for documentation.
For actual HTTP response shapes, use SecretConfigurationResponseCreateUpdate,
SecretConfigurationResponseRetrieved, or SecretListItem (see
SecretResourceServiceStatus for the id/timestamp-only status on secret APIs).
{"apiKeys":[{"name":"my-production-key","displayName":"My Production Key","apiKey":"apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","apiId":"reading-list-api-v1.0","status":"active","createdAt":"2026-04-01T10:30:00Z","createdBy":"admin","expiresAt":null,"source":"local"}],"totalCount":3,"status":"success"}
List of secrets. For security, the spec.value field is omitted for every item in the list; retrieve a single secret by id to obtain the decrypted value.
{"apiVersion":"gateway.api-platform.wso2.com/v1","kind":"Secret","metadata":{"name":"database-password"},"spec":{"displayName":"Database Password","description":"PostgreSQL main database password"},"status":{"id":"database-password","createdAt":"2026-01-05T10:30:00Z","updatedAt":"2026-01-05T10:30:00Z"}}
POST/PUT /secrets response. spec.value is not returned; see SecretConfigurationRequest for create/update request bodies.
{"apiVersion":"gateway.api-platform.wso2.com/v1","kind":"Secret","metadata":{"name":"database-password"},"spec":{"displayName":"Database Password","description":"PostgreSQL main database password","value":"sup3rs3cr3t!"},"status":{"id":"database-password","createdAt":"2026-01-05T10:30:00Z","updatedAt":"2026-01-05T10:30:00Z"}}
GET /secrets/{id} response including decrypted spec.value.