Skip to Content

Update a cached response

PATCHhttps://api.respan.ai/api/caches/{cache_key}/

Update the expiry date of a cached response identified by its public cache key. An entry that has already expired returns 404 and cannot be revived.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Path parameters

Parameter Type Required Description and constraints
cache_key string Required
Organization-scoped cache key returned by the cache list endpoint.

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
-
expiry_date string or null Optional
New expiry time. Setting null or a past time makes the entry unservable: it is no longer served or listed, and later reads and updates return 404. It can still be deleted.
Format: date-time

OpenAPI request schema

{
  "type": "object",
  "properties": {
    "expiry_date": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "New expiry time. Setting `null` or a past time makes the entry unservable: it is no longer served or listed, and later reads and updates return 404. It can still be deleted."
    }
  }
}

Responses

200

Updated cached response.

application/json

Field Type Requirement Description and constraints
$ object Body
-
id integer Optional
Internal numeric ID. Present only for dashboard-JWT responses.
Example: 123
cache_key string Required in parent
Organization-scoped public cache key.
Example: "cached_response_550e8400-e29b-41d4_abc123def456"
prompt_content string Required in parent
Prompt text extracted from the cached request.
Example: "What is the capital of France?"
response_content string Required in parent
Response text extracted from the cached response.
Example: "The capital of France is Paris."
request_content string Optional
Stored request text preview. The current backend serializer truncates this field to roughly the first 100 characters.
Example: "What is the capital of France?"
prompt_messages array<object> Optional
Original prompt message array stored with the cache entry.
Example: [{"role":"user","content":"What is the capital of France?"}]
prompt_messages[] object Array item
-
full_response object Optional
Full cached provider response object.
Example: {"choices":[{"message":{"role":"assistant","content":"The capital of France is Paris."}}]}
hit_count integer Required in parent
Live cache hit count enriched from ClickHouse.
Example: 42
response_time number Optional
Stored response time for the cached entry, in seconds.
Example: 0.5
timestamp string Required in parent
When the cache entry was created.
Format: date-time
Example: "2026-04-10T12:00:00Z"
updated_at string Required in parent
When the cache entry was last updated.
Format: date-time
Example: "2026-04-10T12:00:00Z"
expiry_date string or null Optional
When the cache entry expires.
Format: date-time
Example: "2026-05-10T12:00:00Z"

OpenAPI response schema

{
  "type": "object",
  "required": [
    "cache_key",
    "prompt_content",
    "response_content",
    "hit_count",
    "timestamp",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Internal numeric ID. Present only for dashboard-JWT responses.",
      "example": 123
    },
    "cache_key": {
      "type": "string",
      "description": "Organization-scoped public cache key.",
      "example": "cached_response_550e8400-e29b-41d4_abc123def456"
    },
    "prompt_content": {
      "type": "string",
      "description": "Prompt text extracted from the cached request.",
      "example": "What is the capital of France?"
    },
    "response_content": {
      "type": "string",
      "description": "Response text extracted from the cached response.",
      "example": "The capital of France is Paris."
    },
    "request_content": {
      "type": "string",
      "description": "Stored request text preview. The current backend serializer truncates this field to roughly the first 100 characters.",
      "example": "What is the capital of France?"
    },
    "prompt_messages": {
      "type": "array",
      "description": "Original prompt message array stored with the cache entry.",
      "items": {
        "type": "object"
      },
      "example": [
        {
          "role": "user",
          "content": "What is the capital of France?"
        }
      ]
    },
    "full_response": {
      "type": "object",
      "description": "Full cached provider response object.",
      "example": {
        "choices": [
          {
            "message": {
              "role": "assistant",
              "content": "The capital of France is Paris."
            }
          }
        ]
      }
    },
    "hit_count": {
      "type": "integer",
      "description": "Live cache hit count enriched from ClickHouse.",
      "example": 42
    },
    "response_time": {
      "type": "number",
      "description": "Stored response time for the cached entry, in seconds.",
      "example": 0.5
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "When the cache entry was created.",
      "example": "2026-04-10T12:00:00Z"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the cache entry was last updated.",
      "example": "2026-04-10T12:00:00Z"
    },
    "expiry_date": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "When the cache entry expires.",
      "example": "2026-05-10T12:00:00Z"
    }
  }
}

400

Invalid update.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

403

The API key is missing, invalid or expired, or it can’t update cached responses.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }

404

Cached response not found.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "detail": "Cached response not found" }

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Update a cached response",
  "operationId": "api_caches_partial_update_2",
  "tags": [
    "Caches"
  ],
  "description": "Update the expiry date of a cached response identified by its public cache key. An entry that has already expired returns 404 and cannot be revived.",
  "parameters": [
    {
      "name": "cache_key",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Organization-scoped cache key returned by the cache list endpoint."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "expiry_date": {
              "type": "string",
              "format": "date-time",
              "nullable": true,
              "description": "New expiry time. Setting `null` or a past time makes the entry unservable: it is no longer served or listed, and later reads and updates return 404. It can still be deleted."
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Updated cached response.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "cache_key",
              "prompt_content",
              "response_content",
              "hit_count",
              "timestamp",
              "updated_at"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "description": "Internal numeric ID. Present only for dashboard-JWT responses.",
                "example": 123
              },
              "cache_key": {
                "type": "string",
                "description": "Organization-scoped public cache key.",
                "example": "cached_response_550e8400-e29b-41d4_abc123def456"
              },
              "prompt_content": {
                "type": "string",
                "description": "Prompt text extracted from the cached request.",
                "example": "What is the capital of France?"
              },
              "response_content": {
                "type": "string",
                "description": "Response text extracted from the cached response.",
                "example": "The capital of France is Paris."
              },
              "request_content": {
                "type": "string",
                "description": "Stored request text preview. The current backend serializer truncates this field to roughly the first 100 characters.",
                "example": "What is the capital of France?"
              },
              "prompt_messages": {
                "type": "array",
                "description": "Original prompt message array stored with the cache entry.",
                "items": {
                  "type": "object"
                },
                "example": [
                  {
                    "role": "user",
                    "content": "What is the capital of France?"
                  }
                ]
              },
              "full_response": {
                "type": "object",
                "description": "Full cached provider response object.",
                "example": {
                  "choices": [
                    {
                      "message": {
                        "role": "assistant",
                        "content": "The capital of France is Paris."
                      }
                    }
                  ]
                }
              },
              "hit_count": {
                "type": "integer",
                "description": "Live cache hit count enriched from ClickHouse.",
                "example": 42
              },
              "response_time": {
                "type": "number",
                "description": "Stored response time for the cached entry, in seconds.",
                "example": 0.5
              },
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "description": "When the cache entry was created.",
                "example": "2026-04-10T12:00:00Z"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "description": "When the cache entry was last updated.",
                "example": "2026-04-10T12:00:00Z"
              },
              "expiry_date": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "When the cache entry expires.",
                "example": "2026-05-10T12:00:00Z"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid update.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "403": {
      "description": "The API key is missing, invalid or expired, or it can't update cached responses.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Your API key is invalid or expired, please check your API key in the platform settings."
          }
        }
      }
    },
    "404": {
      "description": "Cached response not found.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Cached response not found"
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}