Self-managed API examples

Use curl examples with the LangCache self-managed Control Plane, Identity Service, and Data Plane APIs.

Redis Iris

These examples show self-managed Control Plane, Identity Service, and Data Plane requests. They assume agent-key authentication as described in Authentication and authorization.

For the complete shared Data Plane schema, see the LangCache API. For the self-managed admin schema, see the Control Plane API reference.

Control Plane API examples

Set variables:

CP_URL="http://localhost:9100"
LC_ADMIN_TOKEN="<admin-token>"

List caches:

curl -sS "$CP_URL/v1/caches" \
  -H "Authorization: Bearer $LC_ADMIN_TOKEN"

Create a cache:

curl -sS -X POST "$CP_URL/v1/caches" \
  -H "Authorization: Bearer $LC_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cache",
    "databaseId": "cache-primary",
    "defaultSearchThreshold": 0.9,
    "defaultTtlMillis": -1,
    "attributes": []
  }'

Response:

{
  "cacheId": "0123456789abcdef0123456789abcdef"
}

databaseId must match an entry in the Control Plane's configured databases registry. defaultSearchThreshold is a float between 0 and 1. defaultTtlMillis accepts -1 or 0 for no expiration, or a positive number of milliseconds.

Get a cache:

curl -sS "$CP_URL/v1/caches/<cache-id>" \
  -H "Authorization: Bearer $LC_ADMIN_TOKEN"

Response fields include status (PROVISIONING, READY, or UNAVAILABLE), the deployment's embeddingProvider/embeddingModel/ embeddingDimensions, and the resolved databaseName.

Update a cache:

curl -sS -X PATCH "$CP_URL/v1/caches/<cache-id>" \
  -H "Authorization: Bearer $LC_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultSearchThreshold": 0.85
  }'

Flush a cache's entries without deleting the cache:

curl -sS -X DELETE "$CP_URL/v1/caches/<cache-id>/entries" \
  -H "Authorization: Bearer $LC_ADMIN_TOKEN"

Delete a cache:

curl -sS -X DELETE "$CP_URL/v1/caches/<cache-id>?flush=true" \
  -H "Authorization: Bearer $LC_ADMIN_TOKEN"

List the deployment's configured embedding providers and models:

curl -sS "$CP_URL/v1/embedding-providers" \
  -H "Authorization: Bearer $LC_ADMIN_TOKEN"

Identity Service API examples

Set variables:

IDS_URL="http://localhost:9200"
IDS_CONTROL_TOKEN="<identity-service-control-token>"

Mint an agent key scoped to one cache:

curl -sS -X POST "$IDS_URL/v1/api-keys" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent-key",
    "grants": [
      {
        "product": "langcache",
        "resourceType": "lc-cache",
        "resourceId": "<cache-id>",
        "actions": ["read", "write"]
      }
    ]
  }'

Response:

{
  "keyId": "0123456789abcdef0123456789abcdef",
  "token": "<agent-key>",
  "createdAt": 1780000000
}

Rotate it later:

curl -sS -X POST "$IDS_URL/v1/api-keys/<key-id>/rotate" \
  -H "Authorization: Bearer $IDS_CONTROL_TOKEN"

Data Plane API examples

Set variables:

DP_URL="http://localhost:9000"
CACHE_ID="<cache-id>"
LC_AGENT_KEY="<agent-key>"

Set a cache entry 

curl -sS -X POST "$DP_URL/v1/caches/$CACHE_ID/entries" \
  -H "Authorization: Bearer $LC_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is the capital of France?",
    "response": "The capital of France is Paris."
  }'

Search for a cached response 

curl -sS -X POST "$DP_URL/v1/caches/$CACHE_ID/entries/search" \
  -H "Authorization: Bearer $LC_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What'"'"'s the capital city of France?"
  }'

Delete a specific entry 

curl -sS -X DELETE "$DP_URL/v1/caches/$CACHE_ID/entries/<entry-id>" \
  -H "Authorization: Bearer $LC_AGENT_KEY"

Delete entries matching attributes 

curl -sS -X DELETE "$DP_URL/v1/caches/$CACHE_ID/entries" \
  -H "Authorization: Bearer $LC_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "topic": "geography"
    }
  }'

Flush all entries in a cache 

curl -sS -X POST "$DP_URL/v1/caches/$CACHE_ID/flush" \
  -H "Authorization: Bearer $LC_AGENT_KEY"

Check cache health 

curl -sS "$DP_URL/v1/caches/$CACHE_ID/health" \
  -H "Authorization: Bearer $LC_AGENT_KEY"

For the full request and response schema for cache entries (set, search, delete, flush), see the LangCache API reference. That shared reference does not yet cover cache health; the example above reflects the same Data Plane API.

RATE THIS PAGE
Back to top ↑