openapi: 3.0.2
info:
  title: Redis LangCache Service
  description: API for managing a [Redis LangCache](https://redis.io/docs/latest/develop/ai/langcache/) service.
  contact:
    name: Redis
    email: support@redis.com
  version: '1.0'
tags:
  - name: Cache Entries
    description: Operations for creating, searching, and deleting cache entries.
servers:
  - url: http://localhost:8080
    description: Generated server URL
paths:
  /v1/caches/{cacheId}/entries/search:
    post:
      tags:
        - Cache Entries
      summary: Search the cache
      description: Searches the cache for entries that match the prompt and attributes. If no entries are found, this endpoint returns an empty array.
      operationId: search
      parameters:
        - name: cacheId
          in: path
          description: The cache to search for the entries.
          schema:
            type: string
            description: The cache to search for the entries.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEntriesRequest'
        required: true
      responses:
        '200':
          description: Cache search completed successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/SearchEntriesResponse'
        '400':
          description: Bad Request
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseContent'
        '401':
          description: Unauthorized
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponseContent'
        '403':
          description: Forbidden
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponseContent'
        '404':
          description: Cache not found
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponseContent'
        '413':
          description: Payload Too Large
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/PayloadTooLargeErrorResponseContent'
        '424':
          description: Failed dependency
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ResourceUnavailableErrorResponseContent'
        '429':
          description: Too Many Requests
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponseContent'
        '500':
          description: An unexpected error occurred
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponseContent'
  /v1/caches/{cacheId}/entries:
    post:
      tags:
        - Cache Entries
      summary: Add a new entry to the cache
      description: Adds an entry to the cache with a prompt and response.
      operationId: set
      parameters:
        - name: cacheId
          in: path
          description: The cache where the entry should be added.
          schema:
            type: string
            description: The cache where the entry should be added.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEntryRequest'
        required: true
      responses:
        '201':
          description: Cache entry added to the cache successfully
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/SetEntryResponse'
        '400':
          description: Bad Request
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseContent'
        '401':
          description: Unauthorized
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponseContent'
        '403':
          description: Forbidden
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponseContent'
        '404':
          description: Cache not found
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponseContent'
        '413':
          description: Payload Too Large
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/PayloadTooLargeErrorResponseContent'
        '424':
          description: Failed dependency
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ResourceUnavailableErrorResponseContent'
        '429':
          description: Too Many Requests
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponseContent'
        '500':
          description: An unexpected error occurred
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponseContent'
    delete:
      tags:
        - Cache Entries
      summary: Delete multiple cache entries
      description: Deletes multiple cache entries based on specified attributes. If no attributes are provided, all entries in the cache are deleted.
      operationId: deleteQuery
      parameters:
        - name: cacheId
          in: path
          description: The cache from which to delete the entries.
          schema:
            type: string
            description: The cache from which to delete the entries.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteEntriesRequest'
        required: true
      responses:
        '200':
          description: Cache entries successfully deleted
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/DeleteEntriesResponse'
        '400':
          description: Bad Request
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseContent'
        '401':
          description: Unauthorized
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponseContent'
        '403':
          description: Forbidden
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponseContent'
        '404':
          description: Cache not found
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponseContent'
        '413':
          description: Payload Too Large
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/PayloadTooLargeErrorResponseContent'
        '424':
          description: Failed dependency
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ResourceUnavailableErrorResponseContent'
        '429':
          description: Too Many Requests
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponseContent'
        '500':
          description: An unexpected error occurred
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponseContent'
  /v1/caches/{cacheId}/entries/{entryId}:
    delete:
      tags:
        - Cache Entries
      summary: Delete a single cache entry
      description: Deletes a single cache entry by the entry ID.
      operationId: delete
      parameters:
        - name: cacheId
          in: path
          description: The cache from which to delete the entry.
          schema:
            type: string
            description: The cache from which to delete the entry.
          required: true
        - name: entryId
          in: path
          description: Unique ID for the cache entry.
          schema:
            type: string
            description: Unique ID for the cache entry.
          required: true
      responses:
        '204':
          description: Cache entry successfully deleted
        '400':
          description: Bad Request
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseContent'
        '401':
          description: Unauthorized
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponseContent'
        '403':
          description: Forbidden
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponseContent'
        '404':
          description: Cache or cache entry not found
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponseContent'
        '413':
          description: Payload Too Large
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/PayloadTooLargeErrorResponseContent'
        '424':
          description: Failed dependency
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ResourceUnavailableErrorResponseContent'
        '429':
          description: Too Many Requests
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponseContent'
        '500':
          description: An unexpected error occurred
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponseContent'
  /v1/caches/{cacheId}/flush:
    post:
      tags:
        - Cache Entries
      summary: Flush all entries from the cache
      description: Flushes all entries from the cache.
      operationId: flush
      parameters:
        - name: cacheId
          in: path
          description: The ID of the cache to flush.
          schema:
            type: string
            description: The ID of the cache to flush.
          required: true
      responses:
        '204':
          description: Cache successfully flushed
        '400':
          description: Bad Request
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponseContent'
        '401':
          description: Unauthorized
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponseContent'
        '403':
          description: Forbidden
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponseContent'
        '404':
          description: Cache not found
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponseContent'
        '413':
          description: Payload Too Large
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/PayloadTooLargeErrorResponseContent'
        '424':
          description: Failed dependency
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ResourceUnavailableErrorResponseContent'
        '429':
          description: Too Many Requests
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponseContent'
        '500':
          description: An unexpected error occurred
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponseContent'
components:
  parameters:
    cacheId:
      name: cacheId
      in: path
      description: The cache from which to delete the entries.
      required: true
      schema:
        type: string
        description: The cache from which to delete the entries.
    entryId:
      name: entryId
      in: path
      description: Unique ID for the cache entry.
      required: true
      schema:
        type: string
        description: Unique ID for the cache entry.
  schemas:
    SearchEntriesRequest:
      required:
        - prompt
      type: object
      properties:
        prompt:
          type: string
          description: The prompt to search for in the cache.
          minLength: 1
          maxLength: 1024
          example: How does semantic caching work?
        similarityThreshold:
          minimum: 0
          maximum: 1
          type: number
          description: The minimum similarity threshold for the cache entry (normalized cosine similarity).
          format: float
          example: 0.9
        attributes:
          $ref: '#/components/schemas/AttributesMap'
        searchStrategies:
          type: array
          items:
            $ref: '#/components/schemas/SearchStrategy'
          description: The search strategies to use for the search, ordered by priority.
      description: Request for searching a cache entry
    SearchEntriesResponse:
      required:
        - data
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CacheEntry'
          description: Array of cache entries matching the search criteria. This array is empty if no entries match the search criteria.
      description: Response representing the result of a successful cache entries search operation
    CacheEntry:
      required:
        - attributes
        - similarity
        - id
        - prompt
        - response
        - searchStrategy
      type: object
      properties:
        id:
          type: string
          description: Unique ID for the cache entry.
          pattern: '^[a-f0-9]{32}$'
          example: 5b84acef3ce360988d1b35adbaaaccb1
        prompt:
          type: string
          description: The prompt associated with the cache entry.
          example: Tell me how semantic caching works
        response:
          type: string
          description: The response associated with the cache entry.
          example: Semantic caching stores and retrieves data based on meaning, not exact matches.
        attributes:
          $ref: '#/components/schemas/AttributesMap'
        similarity:
          type: number
          description: The similarity metric used for similarity comparison.
          format: float
          minimum: 0
          maximum: 1
          example: 0.95
        searchStrategy:
          $ref: '#/components/schemas/SearchStrategy'
      description: A cache entry
    SetEntryRequest:
      required:
        - prompt
        - response
      type: object
      properties:
        prompt:
          example: How does semantic caching work?
          type: string
          description: The prompt for the entry.
          minLength: 1
          maxLength: 1024
        response:
          example: Semantic caching stores and retrieves data based on meaning, not exact matches.
          type: string
          description: The response to the prompt for the entry.
        attributes:
          type: object
          maxProperties: 5
          propertyNames:
            pattern: '^[a-zA-Z0-9_-]{1,32}$'
          additionalProperties:
            type: string
            minLength: 1
            maxLength: 500
            pattern: '^[^,]*$'
          description: Key-value pairs of attributes to be associated with the entry. These can be used for filtering when searching for entries. All attribute names that can be associated with an entry must be defined during cache creation.
          example:
            language: en
            topic: ai
        ttlMillis:
          type: integer
          description: The entry's time-to-live, in milliseconds. If not set, the cache's default TTL is used.
          format: int64
          minimum: 1
          maximum: 31556952000
          example: 60000
      description: Request to add a cache entry to the cache
    SetEntryResponse:
      required:
        - entryId
      type: object
      properties:
        entryId:
          type: string
          description: The ID of the entry that was added to the cache.
          pattern: '^[a-f0-9]{32}$'
      description: Response representing a successful cache entry addition 
    DeleteEntriesRequest:
      required:
        - attributes
      type: object
      description: Request to delete cache entries based on specified attributes
      properties:
        attributes:
          $ref: '#/components/schemas/AttributesMap'
    DeleteEntriesResponse:
      required:
        - deletedEntriesCount
      type: object
      properties:
        deletedEntriesCount:
          type: integer
          description: The number of cache entries successfully deleted.
          format: int64
          example: 42
      description: Response indicating the result of a cache entries deletion operation
    AttributesMap:
      type: object
      additionalProperties:
        type: string
    SearchStrategy:
      type: string
      enum:
        - exact
        - semantic
      x-enumNames:
        - SearchStrategyExact
        - SearchStrategySemantic
    BadRequestErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short summary of the problem type.
          example: Invalid Request
        status:
          type: integer
          default: 400
          description: The HTTP status code generated by the origin server.
        detail:
          type: string
          description: An explanation specific to this problem.
        type:
          $ref: '#/components/schemas/BadRequestErrorURI'
      required:
        - status
        - title
        - type
    BadRequestErrorURI:
      type: string
      enum:
        - /errors/invalid-data
    AuthenticationErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem
                                      type.  It SHOULD NOT change from one occurrence of the
                                      problem to another, except for purposes of localization (e.g., using
                                      proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type: integer
          default: 401
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
        type:
          $ref: '#/components/schemas/AuthenticationErrorUri'
      required:
        - status
        - title
        - type
    AuthenticationErrorUri:
      type: string
      enum:
        - /errors/authentication-failed
    ForbiddenErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem
                                      type.  It SHOULD NOT change from one occurrence of the
                                      problem to another, except for purposes of localization (e.g., using
                                      proactive content negotiation; see [RFC7231], Section 3.4).
          example: Unauthorized
        status:
          type: integer
          default: 403
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
        type:
          $ref: '#/components/schemas/ForbiddenErrorUri'
      required:
        - status
        - title
        - type
    ForbiddenErrorUri:
      type: string
      enum:
        - /errors/insufficient-permissions
    ResourceUnavailableErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem
                                      type.  It SHOULD NOT change from one occurrence of the
                                      problem to another, except for purposes of localization (e.g., using
                                      proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type: integer
          default: 424
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
        type:
          $ref: '#/components/schemas/ResourceUnavailableErrorURI'
      required:
        - status
        - title
        - type
    ResourceUnavailableErrorURI:
      type: string
      enum:
        - /errors/database/resource-database-unavailable
        - /errors/database/out-of-memory
        - /errors/embeddings/unauthorized
        - /errors/embeddings/too-many-requests
        - /errors/cache/index-not-found
    PayloadTooLargeErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem
                                      type.  It SHOULD NOT change from one occurrence of the
                                      problem to another, except for purposes of localization (e.g., using
                                      proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type: integer
          default: 413
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
        type:
          $ref: '#/components/schemas/PayloadTooLargeErrorURI'
      required:
        - status
        - title
        - type
    PayloadTooLargeErrorURI:
      type: string
      enum:
        - /errors/payload-too-large
    TooManyRequestsErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem
                                      type.  It SHOULD NOT change from one occurrence of the
                                      problem to another, except for purposes of localization (e.g., using
                                      proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type: integer
          default: 429
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
        type:
          $ref: '#/components/schemas/TooManyRequestsErrorURI'
      required:
        - status
        - title
        - type
    TooManyRequestsErrorURI:
      type: string
      enum:
        - /errors/too-many-requests
    NotFoundErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem
                                      type.  It SHOULD NOT change from one occurrence of the
                                      problem to another, except for purposes of localization (e.g., using
                                      proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type: integer
          default: 404
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
        type:
          $ref: '#/components/schemas/NotFoundErrorURI'
      required:
        - status
        - title
        - type
    NotFoundErrorURI:
      type: string
      enum:
        - /errors/resource/not-found
        - /errors/cache/not-found
        - /errors/cache/entry/not-found
        - /errors/token/not-found
    UnexpectedErrorResponseContent:
      type: object
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem
                                      type.  It SHOULD NOT change from one occurrence of the
                                      problem to another, except for purposes of localization (e.g., using
                                      proactive content negotiation; see [RFC7231], Section 3.4).
        status:
          type: integer
          default: 500
          description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
        type:
          $ref: '#/components/schemas/UnexpectedErrorURI'
      required:
        - status
        - title
        - type
    UnexpectedErrorURI:
      type: string
      enum:
        - /errors/unexpected-error
        - /errors/cache/authentication
        - /errors/cache/unexpected-error
        - /errors/embeddings/unexpected-error
