Skip to main content
Manually remove a specific entry from the semantic cache. This deletes the entry from both the Qdrant vector index and the Redis key-value store.
This endpoint is only available when the semantic cache is enabled. If the cache is not configured, the gateway does not register this route and requests will return 404 Not Found.

​
Endpoint

DELETE /v1/cache/{id}

​
When to use

Use this endpoint when a cached response is known to be stale or incorrect. Common scenarios:
  • The upstream model’s knowledge has been updated and the cached answer is outdated.
  • A cached response contained an error and you need to force a fresh generation on the next identical query.
  • You are testing the gateway’s routing behavior and want to clear a specific cache hit.

​
Path parameters

​
id
string
required
The unique identifier of the cache entry to evict. This is the UUID assigned when the entry was inserted — the same value used as the Qdrant point ID and as the suffix of the Redis key (cache:<id>).
Cache entry IDs are UUIDs in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx. You can obtain an entry’s ID by inspecting the Qdrant collection directly, or by adding tracing to your application to capture IDs at insert time.

​
Responses

​
Success

Returns 204 No Content with an empty body when the entry is successfully evicted from both Qdrant and Redis. 
HTTP/1.1 204 No Content

​
Error responses

All errors follow the standard error format: 
{
  "error": {
    "message": "<human-readable message>",
    "type": "<error_type>"
  }
}
StatustypeCause
400 Bad Requestinvalid_request_errorNo ID was provided in the path (e.g. DELETE /v1/cache/), or the request used a method other than DELETE.
500 Internal Server Errorserver_errorThe eviction failed — for example, Qdrant or Redis returned an error during deletion.

​
Example

curl http://localhost:8080/v1/cache/3f7a1c2e-84b0-4d9f-a3e1-0c5b2d6f9e17 \
  --request DELETE
A successful eviction returns no body: 
HTTP/1.1 204 No Content
X-Request-ID: a3f2e1b0c9d84765
If the ID is omitted from the path: 
{
  "error": {
    "message": "cache entry id is required",
    "type": "invalid_request_error"
  }
}

​
Implementation details

When Evict is called with an ID, the gateway performs two operations in sequence:
  1. Deletes the Qdrant point with the given ID from the configured vector collection.
  2. Deletes the Redis key cache:<id>.
Both operations must succeed for the eviction to complete. If either fails, a 500 error is returned. There is no partial-eviction state exposed to the caller.

Build docs developers (and LLMs) love

Get started for freeTalk to us