{
  "schema_version": 2,
  "id": "operate/iris/langcache/self-managed/api-examples",
  "title": "Self-managed API examples",
  "url": "https://redis.io/docs/latest/operate/iris/langcache/self-managed/api-examples/",
  "summary": "Use curl examples with the LangCache self-managed Control Plane, Identity Service, and Data Plane APIs.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-09-11T13:23:44+03:00",
  "page_type": "content",
  "content_hash": "f2e5a1f1aaa6cd209bb5d3a857aa3cdba9bc267e9b61ef69d0ca92883ed65bb3",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "These examples show self-managed Control Plane, Identity Service, and Data\nPlane requests. They assume agent-key authentication as described in\n[Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication).\n\nFor the complete shared Data Plane schema, see the\n[LangCache API](https://redis.io/docs/latest/develop/ai/context-engine/langcache/api-reference).\nFor the self-managed admin schema, see the\n[Control Plane API reference](https://redis.io/docs/latest/operate/iris/langcache/self-managed/control-plane-api-reference)."
    },
    {
      "id": "control-plane-api-examples",
      "title": "Control Plane API examples",
      "role": "content",
      "text": "Set variables:\n\n[code example]\n\nList caches:\n\n[code example]\n\nCreate a cache:\n\n[code example]\n\nResponse:\n\n[code example]\n\n`databaseId` must match an entry in the Control Plane's configured\n`databases` registry. `defaultSearchThreshold` is a float between 0 and 1.\n`defaultTtlMillis` accepts `-1` or `0` for no expiration, or a positive\nnumber of milliseconds.\n\nGet a cache:\n\n[code example]\n\nResponse fields include `status` (`PROVISIONING`, `READY`, or\n`UNAVAILABLE`), the deployment's `embeddingProvider`/`embeddingModel`/\n`embeddingDimensions`, and the resolved `databaseName`.\n\nUpdate a cache:\n\n[code example]\n\nFlush a cache's entries without deleting the cache:\n\n[code example]\n\nDelete a cache:\n\n[code example]\n\nList the deployment's configured embedding providers and models:\n\n[code example]"
    },
    {
      "id": "identity-service-api-examples",
      "title": "Identity Service API examples",
      "role": "content",
      "text": "Set variables:\n\n[code example]\n\nMint an agent key scoped to one cache:\n\n[code example]\n\nResponse:\n\n[code example]\n\nRotate it later:\n\n[code example]"
    },
    {
      "id": "data-plane-api-examples",
      "title": "Data Plane API examples",
      "role": "content",
      "text": "Set variables:\n\n[code example]"
    },
    {
      "id": "set-a-cache-entry",
      "title": "Set a cache entry",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "search-for-a-cached-response",
      "title": "Search for a cached response",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "delete-a-specific-entry",
      "title": "Delete a specific entry",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "delete-entries-matching-attributes",
      "title": "Delete entries matching attributes",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "flush-all-entries-in-a-cache",
      "title": "Flush all entries in a cache",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "check-cache-health",
      "title": "Check cache health",
      "role": "content",
      "text": "[code example]\n\nFor the full request and response schema for cache entries (set, search,\ndelete, flush), see the\n[LangCache API reference](https://redis.io/docs/latest/develop/ai/context-engine/langcache/api-reference).\nThat shared reference does not yet cover cache health; the example above\nreflects the same Data Plane API."
    }
  ],
  "examples": [
    {
      "id": "control-plane-api-examples-ex0",
      "language": "bash",
      "code": "CP_URL=\"http://localhost:9100\"\nLC_ADMIN_TOKEN=\"<admin-token>\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex1",
      "language": "bash",
      "code": "curl -sS \"$CP_URL/v1/caches\" \\\n  -H \"Authorization: Bearer $LC_ADMIN_TOKEN\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex2",
      "language": "bash",
      "code": "curl -sS -X POST \"$CP_URL/v1/caches\" \\\n  -H \"Authorization: Bearer $LC_ADMIN_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-cache\",\n    \"databaseId\": \"cache-primary\",\n    \"defaultSearchThreshold\": 0.9,\n    \"defaultTtlMillis\": -1,\n    \"attributes\": []\n  }'",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex3",
      "language": "json",
      "code": "{\n  \"cacheId\": \"0123456789abcdef0123456789abcdef\"\n}",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex4",
      "language": "bash",
      "code": "curl -sS \"$CP_URL/v1/caches/<cache-id>\" \\\n  -H \"Authorization: Bearer $LC_ADMIN_TOKEN\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex5",
      "language": "bash",
      "code": "curl -sS -X PATCH \"$CP_URL/v1/caches/<cache-id>\" \\\n  -H \"Authorization: Bearer $LC_ADMIN_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"defaultSearchThreshold\": 0.85\n  }'",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex6",
      "language": "bash",
      "code": "curl -sS -X DELETE \"$CP_URL/v1/caches/<cache-id>/entries\" \\\n  -H \"Authorization: Bearer $LC_ADMIN_TOKEN\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex7",
      "language": "bash",
      "code": "curl -sS -X DELETE \"$CP_URL/v1/caches/<cache-id>?flush=true\" \\\n  -H \"Authorization: Bearer $LC_ADMIN_TOKEN\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "control-plane-api-examples-ex8",
      "language": "bash",
      "code": "curl -sS \"$CP_URL/v1/embedding-providers\" \\\n  -H \"Authorization: Bearer $LC_ADMIN_TOKEN\"",
      "section_id": "control-plane-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex0",
      "language": "bash",
      "code": "IDS_URL=\"http://localhost:9200\"\nIDS_CONTROL_TOKEN=\"<identity-service-control-token>\"",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex1",
      "language": "bash",
      "code": "curl -sS -X POST \"$IDS_URL/v1/api-keys\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-agent-key\",\n    \"grants\": [\n      {\n        \"product\": \"langcache\",\n        \"resourceType\": \"lc-cache\",\n        \"resourceId\": \"<cache-id>\",\n        \"actions\": [\"read\", \"write\"]\n      }\n    ]\n  }'",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex2",
      "language": "json",
      "code": "{\n  \"keyId\": \"0123456789abcdef0123456789abcdef\",\n  \"token\": \"<agent-key>\",\n  \"createdAt\": 1780000000\n}",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "identity-service-api-examples-ex3",
      "language": "bash",
      "code": "curl -sS -X POST \"$IDS_URL/v1/api-keys/<key-id>/rotate\" \\\n  -H \"Authorization: Bearer $IDS_CONTROL_TOKEN\"",
      "section_id": "identity-service-api-examples"
    },
    {
      "id": "data-plane-api-examples-ex0",
      "language": "bash",
      "code": "DP_URL=\"http://localhost:9000\"\nCACHE_ID=\"<cache-id>\"\nLC_AGENT_KEY=\"<agent-key>\"",
      "section_id": "data-plane-api-examples"
    },
    {
      "id": "set-a-cache-entry-ex0",
      "language": "bash",
      "code": "curl -sS -X POST \"$DP_URL/v1/caches/$CACHE_ID/entries\" \\\n  -H \"Authorization: Bearer $LC_AGENT_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"What is the capital of France?\",\n    \"response\": \"The capital of France is Paris.\"\n  }'",
      "section_id": "set-a-cache-entry"
    },
    {
      "id": "search-for-a-cached-response-ex0",
      "language": "bash",
      "code": "curl -sS -X POST \"$DP_URL/v1/caches/$CACHE_ID/entries/search\" \\\n  -H \"Authorization: Bearer $LC_AGENT_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"prompt\": \"What'\"'\"'s the capital city of France?\"\n  }'",
      "section_id": "search-for-a-cached-response"
    },
    {
      "id": "delete-a-specific-entry-ex0",
      "language": "bash",
      "code": "curl -sS -X DELETE \"$DP_URL/v1/caches/$CACHE_ID/entries/<entry-id>\" \\\n  -H \"Authorization: Bearer $LC_AGENT_KEY\"",
      "section_id": "delete-a-specific-entry"
    },
    {
      "id": "delete-entries-matching-attributes-ex0",
      "language": "bash",
      "code": "curl -sS -X DELETE \"$DP_URL/v1/caches/$CACHE_ID/entries\" \\\n  -H \"Authorization: Bearer $LC_AGENT_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"attributes\": {\n      \"topic\": \"geography\"\n    }\n  }'",
      "section_id": "delete-entries-matching-attributes"
    },
    {
      "id": "flush-all-entries-in-a-cache-ex0",
      "language": "bash",
      "code": "curl -sS -X POST \"$DP_URL/v1/caches/$CACHE_ID/flush\" \\\n  -H \"Authorization: Bearer $LC_AGENT_KEY\"",
      "section_id": "flush-all-entries-in-a-cache"
    },
    {
      "id": "check-cache-health-ex0",
      "language": "bash",
      "code": "curl -sS \"$DP_URL/v1/caches/$CACHE_ID/health\" \\\n  -H \"Authorization: Bearer $LC_AGENT_KEY\"",
      "section_id": "check-cache-health"
    }
  ]
}