{
  "id": "api-examples",
  "title": "Use the LangCache API and SDK",
  "url": "https://redis.io/docs/latest/develop/ai/langcache/api-examples/",
  "summary": "Learn to use the Redis LangCache API for semantic caching.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-04-09T10:29:34-04:00",
  "page_type": "content",
  "content_hash": "9f99356b4e3bd7e84980fb743fbbd919209dad86ae41c436b560fc18902aa74b",
  "sections": [
    {
      "id": "authentication",
      "title": "Authentication",
      "role": "security",
      "text": "To access the LangCache API, you need:\n\n- LangCache API base URL\n- LangCache service API key\n- Cache ID\n\nWhen you call the API, you need to pass the LangCache API key in the `Authorization` header as a Bearer token and the Cache ID as the `cacheId` path parameter.\n\nFor example:\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]\n\n\n\nThis example expects several variables to be set in the shell:\n\n- **$HOST** - the LangCache API base URL\n- **$CACHE_ID** - the Cache ID of your cache\n- **$API_KEY** - The LangCache API token"
    },
    {
      "id": "examples",
      "title": "Examples",
      "role": "example",
      "text": ""
    },
    {
      "id": "search-langcache-for-similar-responses",
      "title": "Search LangCache for similar responses",
      "role": "content",
      "text": "Use [`POST /v1/caches/{cacheId}/entries/search`]() to search the cache for matching responses to a user prompt.\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]\n\n\n\nPlace this call in your client app right before you call your LLM's REST API. If LangCache returns a response, you can send that response back to the user instead of calling the LLM.\n\nIf LangCache does not return a response, you should call your LLM's REST API to generate a new response. After you get a response from the LLM, you can [store it in LangCache](#store-a-new-response-in-langcache) for future use.\n\n#### Attributes\nYou can also scope the responses returned from LangCache by adding an `attributes` object to the request. LangCache will only return responses that match the attributes you specify.\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]\n\n\n\n#### Search strategies\nLangCache supports two search strategies when looking for a cached response:\n\n- **`exact`**: Returns a result only when the stored prompt matches the query exactly (case insensitive).\n- `**semantic**`: Uses vector similarity to find semantically similar prompts and responses.\n\nBy default, LangCache uses `semantic` search only. You can specify one or more search strategies in the request body.\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]"
    },
    {
      "id": "store-a-new-response-in-langcache",
      "title": "Store a new response in LangCache",
      "role": "content",
      "text": "Use [`POST /v1/caches/{cacheId}/entries`]() to store a new response in the cache.\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]\n\n\n\nPlace this call in your client app after you get a response from the LLM. This will store the response in the cache for future use.\n\nYou can also store the responses with custom attributes by adding an `attributes` object to the request.\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]"
    },
    {
      "id": "delete-cached-responses",
      "title": "Delete cached responses",
      "role": "content",
      "text": "Use [`DELETE /v1/caches/{cacheId}/entries/{entryId}`]() to delete a cached response from the cache.\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]\n\n\n\nYou can also use [`DELETE /v1/caches/{cacheId}/entries`]() to delete multiple cached responses based on the `attributes` you specify. If you specify multiple `attributes`, LangCache will delete entries that contain all given attributes.\n\n\nIf you do not specify any `attributes`, all responses in the cache will be deleted. This cannot be undone.\n\n\n<br/>\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]"
    },
    {
      "id": "flush-the-cache",
      "title": "Flush the cache",
      "role": "content",
      "text": "Use\n[POST /v1/caches/{cacheId}/flush](https://redis.io/docs/latest/develop/ai/langcache/api-reference/#tag/Cache-Entries/operation/flush)\nto flush all entries from the cache.\n\n#### Code Examples\n\n**Redis CLI:**\n\n[code example]\n\n**Available in:** Redis CLI, JavaScript (Node.js), Python\n\n**JavaScript (Node.js):**\n\n[code example]\n\n**Python:**\n\n[code example]"
    }
  ],
  "examples": [
    {
      "id": "authentication-ex0",
      "language": "plaintext",
      "code": "curl -s -X POST \"https://$HOST/v1/caches/$CACHE_ID/entries/search\" \\\n    -H \"accept: application/json\" \\\n    -H \"Authorization: Bearer $API_KEY\" \\\n    -d '{ \"prompt\": \"What is semantic caching\" }'",
      "section_id": "authentication"
    },
    {
      "id": "authentication-ex1",
      "language": "javascript",
      "code": "import { LangCache } from \"@redis-ai/langcache\";\n\nconst langCache = new LangCache({\n    serverURL: \"https://\" + process.env.HOST,\n    cacheId: process.env.CACHE_ID,\n    apiKey: process.env.API_KEY,\n  });",
      "section_id": "authentication"
    },
    {
      "id": "authentication-ex2",
      "language": "python",
      "code": "from langcache import LangCache\nimport os\n\nlang_cache = LangCache(\n    server_url=f\"https://{os.getenv('HOST', '')}\",\n    cache_id=os.getenv(\"CACHE_ID\", \"\"),\n    api_key=os.getenv(\"API_KEY\", \"\")\n)",
      "section_id": "authentication"
    },
    {
      "id": "search-langcache-for-similar-responses-ex0",
      "language": "plaintext",
      "code": "POST https://[host]/v1/caches/{cacheId}/entries/search\n{\n    \"prompt\": \"User prompt text\"\n}",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex1",
      "language": "javascript",
      "code": "async function searchBasic() {\n    const result = await langCache.search({\n      prompt: \"User prompt text\",\n      similarityThreshold: 0.9,\n    });\n\n    console.log(result);\n}\n\nsearchBasic();",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex2",
      "language": "python",
      "code": "res = lang_cache.search(\n    prompt=\"User prompt text\",\n    similarity_threshold=0.9\n)\n\nprint(res)",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex3",
      "language": "plaintext",
      "code": "POST https://[host]/v1/caches/{cacheId}/entries/search\n{\n    \"prompt\": \"User prompt text\",\n    \"attributes\": {\n        \"customAttributeName\": \"customAttributeValue\"\n    }\n}",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex4",
      "language": "javascript",
      "code": "async function searchAttributes() {\n    const result = await langCache.search({\n      prompt: \"User prompt text\",\n      attributes: {\n        \"customAttributeName\": \"customAttributeValue\",\n      },\n      similarityThreshold: 0.9,\n    });\n\n    console.log(result);\n}\n\nsearchAttributes();",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex5",
      "language": "python",
      "code": "res = lang_cache.search(\n    prompt=\"User prompt text\",\n    attributes={\"customAttributeName\": \"customAttributeValue\"},\n    similarity_threshold=0.9,\n)\n\nprint(res)",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex6",
      "language": "plaintext",
      "code": "POST https://[host]/v1/caches/{cacheId}/entries/search\n{\n    \"prompt\": \"User prompt text\",\n    \"searchStrategies\": [\"exact\", \"semantic\"]\n}",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex7",
      "language": "javascript",
      "code": "import { SearchStrategy } from '@redis-ai/langcache/models/searchstrategy.js';\n\nasync function searchStrategies() {\n    const result = await langCache.search({\n      prompt: \"User prompt text\",\n      searchStrategies: [SearchStrategy.Exact, SearchStrategy.Semantic],\n      similarityThreshold: 0.9,\n    });\n\n    console.log(result);\n}\n\nsearchStrategies();",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "search-langcache-for-similar-responses-ex8",
      "language": "python",
      "code": "from langcache.models import SearchStrategy\n\nres = lang_cache.search(\n    prompt=\"User prompt text\",\n    search_strategies=[SearchStrategy.EXACT, SearchStrategy.SEMANTIC],\n    similarity_threshold=0.9,\n)\n\nprint(res)",
      "section_id": "search-langcache-for-similar-responses"
    },
    {
      "id": "store-a-new-response-in-langcache-ex0",
      "language": "plaintext",
      "code": "POST https://[host]/v1/caches/{cacheId}/entries\n{\n    \"prompt\": \"User prompt text\",\n    \"response\": \"LLM response text\"\n}",
      "section_id": "store-a-new-response-in-langcache"
    },
    {
      "id": "store-a-new-response-in-langcache-ex1",
      "language": "javascript",
      "code": "async function storeBasic() {\n    const result = await langCache.set({\n      prompt: \"User prompt text\",\n      response: \"LLM response text\",\n    });\n\n    console.log(result);\n}\n\nstoreBasic();",
      "section_id": "store-a-new-response-in-langcache"
    },
    {
      "id": "store-a-new-response-in-langcache-ex2",
      "language": "python",
      "code": "res = lang_cache.set(\n    prompt=\"User prompt text\",\n    response=\"LLM response text\",\n)\n\nprint(res)",
      "section_id": "store-a-new-response-in-langcache"
    },
    {
      "id": "store-a-new-response-in-langcache-ex3",
      "language": "plaintext",
      "code": "POST https://[host]/v1/caches/{cacheId}/entries\n{\n    \"prompt\": \"User prompt text\",\n    \"response\": \"LLM response text\",\n    \"attributes\": {\n        \"customAttributeName\": \"customAttributeValue\"\n    }\n}",
      "section_id": "store-a-new-response-in-langcache"
    },
    {
      "id": "store-a-new-response-in-langcache-ex4",
      "language": "javascript",
      "code": "async function storeAttributes() {\n    const result = await langCache.set({\n      prompt: \"User prompt text\",\n      response: \"LLM response text\",\n      attributes: {\n        \"customAttributeName\": \"customAttributeValue\",\n      },\n    });\n\n    console.log(result);\n}\n\nstoreAttributes();",
      "section_id": "store-a-new-response-in-langcache"
    },
    {
      "id": "store-a-new-response-in-langcache-ex5",
      "language": "python",
      "code": "res = lang_cache.set(\n    prompt=\"User prompt text\",\n    response=\"LLM response text\",\n    attributes={\"customAttributeName\": \"customAttributeValue\"},\n)\n\nprint(res)",
      "section_id": "store-a-new-response-in-langcache"
    },
    {
      "id": "delete-cached-responses-ex0",
      "language": "plaintext",
      "code": "DELETE https://[host]/v1/caches/{cacheId}/entries/{entryId}",
      "section_id": "delete-cached-responses"
    },
    {
      "id": "delete-cached-responses-ex1",
      "language": "javascript",
      "code": "async function deleteEntry() {\n    const result = await langCache.deleteById({\n      entryId: \"<entryId>\",\n    });\n\n    console.log(result);\n}\n\ndeleteEntry();",
      "section_id": "delete-cached-responses"
    },
    {
      "id": "delete-cached-responses-ex2",
      "language": "python",
      "code": "res = lang_cache.delete_by_id(entry_id=\"<entryId>\")\n\nprint(res)",
      "section_id": "delete-cached-responses"
    },
    {
      "id": "delete-cached-responses-ex3",
      "language": "plaintext",
      "code": "DELETE https://[host]/v1/caches/{cacheId}/entries\n{\n    \"attributes\": {\n        \"customAttributeName\": \"customAttributeValue\"\n    }\n}",
      "section_id": "delete-cached-responses"
    },
    {
      "id": "delete-cached-responses-ex4",
      "language": "javascript",
      "code": "async function deleteQuery() {\n    const result = await langCache.deleteQuery({\n      attributes: {\n        \"customAttributeName\": \"customAttributeValue\",\n      },\n    });\n\n    console.log(result);\n}\n\ndeleteQuery();",
      "section_id": "delete-cached-responses"
    },
    {
      "id": "delete-cached-responses-ex5",
      "language": "python",
      "code": "res = lang_cache.delete_query(\n    attributes={\"customAttributeName\": \"customAttributeValue\"},\n)\n\nprint(res)",
      "section_id": "delete-cached-responses"
    },
    {
      "id": "flush-the-cache-ex0",
      "language": "plaintext",
      "code": "POST https://[host]/v1/caches/{cacheId}/flush",
      "section_id": "flush-the-cache"
    },
    {
      "id": "flush-the-cache-ex1",
      "language": "javascript",
      "code": "async function flush() {\n    await langCache.flush();\n}\n\nflush();",
      "section_id": "flush-the-cache"
    },
    {
      "id": "flush-the-cache-ex2",
      "language": "python",
      "code": "lang_cache.flush()",
      "section_id": "flush-the-cache"
    }
  ]
}