Create Cache Policy

POST /environments/{env_id}/cache_policies

Create Cache Policy

Create a prompt-response cache rule in an environment. Policy names are unique within the environment, and the name and backend cannot be changed after creation.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.

Request body

Content type: application/json

• name (string, required): Human-readable policy name, unique within the environment.

• enabled (boolean, optional): Policies are created enabled unless this is false.

• backend (string, optional): Where cached responses are stored. memory keeps an in-process cache on each gateway instance. redis uses the shared Redis configured on the gateway (cache.redis); a gateway without one disables caching for the policy's requests and logs a warning. Fixed at creation.

• ttl_seconds (integer, optional): How long a cached response stays servable, in seconds. Defaults to 3600 (1 hour); the ceiling is 7 days. To stop serving cached responses, disable the policy rather than setting a zero TTL.

• applies_to (string, optional): Which traffic the policy covers: all for every request in the environment, model:<model alias> for one model, or api_key:<key id> for one caller API key. Defaults to all.

• scope (string, optional): Sharing boundary for entries created under a policy, applied to both exact and semantic matching. api_key (the default) keeps entries private to the API key that created them — one caller's answers are never replayed to another. env shares entries across every API key in the environment; pick it for shared-knowledge traffic (FAQ, documentation Q&A) where cross-caller reuse is the point.

• semantic (object, optional): Embedding-similarity matching for a cache policy. When configured, a request that misses exact matching is embedded and compared against stored entries; the nearest entry at or above threshold cosine similarity is served. Only fully textual requests participate — requests containing images, audio, or tool calls always take the exact path. On the redis backend this additionally requires a Redis server with vector search (Redis 8 or later, or the search module); the gateway probes support at startup and keeps the policy exact-only when it is missing.

• semantic.embedding_model_id (string, required): ID of the embedding model used to embed requests. Must reference a model of kind embedding in the same environment.

• semantic.threshold (number, required): Minimum cosine similarity for a stored entry to be served. Higher is stricter; values below 0.9 noticeably increase wrong-answer risk for most embedding models.

• semantic.max_entries (integer, optional): Upper bound on stored entries for this policy on the memory backend (oldest evicted first). Defaults to 1000. The redis backend bounds growth by TTL and ignores this value.

• semantic.embedding_timeout_ms (integer, optional): Per-call deadline for the embedding request in milliseconds. 0 or omitted disables the embedding-specific deadline. On timeout the request proceeds to the upstream uncached.

Responses

• 201: Created

• cache_policy (object, required): A prompt-response cache rule. When an enabled policy covers a request, the gateway serves an identical repeated request from cache instead of calling the upstream provider.

• cache_policy.id (string, required): Cache policy ID.

• cache_policy.env_id (string, required): Environment ID that owns this policy.

• cache_policy.name (string, required): Human-readable policy name, unique within the environment. Fixed at creation.

• cache_policy.enabled (boolean, required): Disabled policies are kept but the gateway no longer consults them.

• cache_policy.backend (string, required): Where cached responses are stored. memory keeps an in-process cache on each gateway instance. redis uses the shared Redis configured on the gateway (cache.redis); a gateway without one disables caching for the policy's requests and logs a warning. Fixed at creation.

• cache_policy.ttl_seconds (integer, required): How long a cached response stays servable, in seconds.

• cache_policy.applies_to (string, required): Which traffic the policy covers: all for every request in the environment, model:<model alias> for one model, or api_key:<key id> for one caller API key.

• cache_policy.scope (string, required): Sharing boundary for entries created under a policy, applied to both exact and semantic matching. api_key (the default) keeps entries private to the API key that created them — one caller's answers are never replayed to another. env shares entries across every API key in the environment; pick it for shared-knowledge traffic (FAQ, documentation Q&A) where cross-caller reuse is the point.

• cache_policy.purge_generation (integer, required): Server-managed invalidation counter. Each purge increments it, making every entry created earlier unreachable at once. Read-only — see the purge operation.

• cache_policy.semantic (object, optional): Embedding-similarity matching for a cache policy. When configured, a request that misses exact matching is embedded and compared against stored entries; the nearest entry at or above threshold cosine similarity is served. Only fully textual requests participate — requests containing images, audio, or tool calls always take the exact path. On the redis backend this additionally requires a Redis server with vector search (Redis 8 or later, or the search module); the gateway probes support at startup and keeps the policy exact-only when it is missing.

• cache_policy.semantic.embedding_model_id (string, required): ID of the embedding model used to embed requests. Must reference a model of kind embedding in the same environment.

• cache_policy.semantic.threshold (number, required): Minimum cosine similarity for a stored entry to be served. Higher is stricter; values below 0.9 noticeably increase wrong-answer risk for most embedding models.

• cache_policy.semantic.max_entries (integer, optional): Upper bound on stored entries for this policy on the memory backend (oldest evicted first). Defaults to 1000. The redis backend bounds growth by TTL and ignores this value.

• cache_policy.semantic.embedding_timeout_ms (integer, optional): Per-call deadline for the embedding request in milliseconds. 0 or omitted disables the embedding-specific deadline. On timeout the request proceeds to the upstream uncached.

• cache_policy.created_at (string, required): Time when the policy was created.

• cache_policy.updated_at (string, required): Time when the policy was last updated.

• warnings (array, optional): Present on save and purge operations when some data plane nodes in the environment run a gateway version that will not execute part of the saved policy — its sharing scope, semantic block, or purge generation. Never present on reads.

• warnings[].code (string, required): How affected nodes treat the saved resource. field_ignored: the resource stays in service on those nodes but the named field has no effect there — beware when the field is restrictive, since the restriction is silently not enforced. row_rejected: those nodes refuse the whole resource, so it stops serving there entirely (or, if a previously accepted version exists, they keep serving the old values).

• warnings[].field (string, required): Dot-separated path of the field that triggered the warning, as delivered to gateway nodes.

• warnings[].min_dp_version (string, required): Oldest gateway version that fully executes the field. The literal value unreleased means no released gateway version executes it yet.

• warnings[].affected_dp_count (integer, required): Number of currently registered nodes in the environment running an older gateway version than min_dp_version.

• warnings[].affected_dp_versions (array, required): Distinct gateway versions reported by the affected nodes, capped at five entries. Nodes that report no version appear as unknown.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to POST /environments/{env_id}/cache_policies, response 400 above.

• 403: Authenticated request is not permitted. Response fields (application/json): identical to POST /environments/{env_id}/cache_policies, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to POST /environments/{env_id}/cache_policies, response 400 above.

• 409: Request conflicts with current resource state. Response fields (application/json): identical to POST /environments/{env_id}/cache_policies, response 400 above.

cURL

curl -X POST '$AISIX_CP/environments/{env_id}/cache_policies' -H 'Authorization: Bearer $AISIX_TOKEN'