# Self-managed API examples

```json metadata
{
  "schema_version": 2,
  "title": "Self-managed API examples",
  "description": "Use curl examples with the LangCache self-managed Control Plane, Identity Service, and Data Plane APIs.",
  "categories": ["docs","operate","iris"],
  "tableOfContents": {"sections":[{"id":"control-plane-api-examples","title":"Control Plane API examples"},{"id":"identity-service-api-examples","title":"Identity Service API examples"},{"children":[{"id":"set-a-cache-entry","title":"Set a cache entry"},{"id":"search-for-a-cached-response","title":"Search for a cached response"},{"id":"delete-a-specific-entry","title":"Delete a specific entry"},{"id":"delete-entries-matching-attributes","title":"Delete entries matching attributes"},{"id":"flush-all-entries-in-a-cache","title":"Flush all entries in a cache"},{"id":"check-cache-health","title":"Check cache health"}],"id":"data-plane-api-examples","title":"Data Plane API examples"}]}

,
  "codeExamples": []
}
```


These examples show self-managed Control Plane, Identity Service, and Data
Plane requests. They assume agent-key authentication as described in
[Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication).

For the complete shared Data Plane schema, see the
[LangCache API](https://redis.io/docs/latest/develop/ai/context-engine/langcache/api-reference).
For the self-managed admin schema, see the
[Control Plane API reference](https://redis.io/docs/latest/operate/iris/langcache/self-managed/control-plane-api-reference).

## Control Plane API examples

Set variables:

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

List caches:

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

Create a cache:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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:

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

Delete a cache:

```bash
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:

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

## Identity Service API examples

Set variables:

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

Mint an agent key scoped to one cache:

```bash
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:

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

Rotate it later:

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

## Data Plane API examples

Set variables:

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

### Set a cache entry

```bash
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

```bash
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

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

### Delete entries matching attributes

```bash
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

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

### Check cache health

```bash
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](https://redis.io/docs/latest/develop/ai/context-engine/langcache/api-reference).
That shared reference does not yet cover cache health; the example above
reflects the same Data Plane API.