Skip to Content

Delete cached responses in bulk

DELETEhttps://api.respan.ai/api/caches/bulk/

Delete cached responses using exactly one selector: cache_keys, ids, or all: true. Up to 1,000 keys or IDs can be deleted per request. ids uses internal integer IDs and is JWT-only; API-key clients should use cache_keys or all. Rate limit: 60 requests per minute per organization for API-key calls (shared across API keys) and per user for JWT calls.

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

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
Exactly one deletion mode is required.
Minimum properties: 1
Maximum properties: 1
Additional properties are not allowed
cache_keys array<string> Optional
Cache keys to delete. Supported for API key and JWT authentication.
Minimum items: 1
Maximum items: 1000
Example: ["cached_response_550e8400"]
cache_keys[] string Array item
-
ids array<integer> Optional
Internal numeric cache entry IDs to delete. JWT only.
Minimum items: 1
Maximum items: 1000
Example: [123,124,125]
ids[] integer Array item
-
all boolean Optional
Set to true to delete all cached responses for the current organization. The server rejects false.
Example: true

OpenAPI request schema

{
  "type": "object",
  "description": "Exactly one deletion mode is required.",
  "properties": {
    "cache_keys": {
      "type": "array",
      "description": "Cache keys to delete. Supported for API key and JWT authentication.",
      "items": {
        "type": "string"
      },
      "example": [
        "cached_response_550e8400"
      ],
      "minItems": 1,
      "maxItems": 1000
    },
    "ids": {
      "type": "array",
      "description": "Internal numeric cache entry IDs to delete. JWT only.",
      "items": {
        "type": "integer"
      },
      "example": [
        123,
        124,
        125
      ],
      "minItems": 1,
      "maxItems": 1000
    },
    "all": {
      "type": "boolean",
      "description": "Set to true to delete all cached responses for the current organization. The server rejects false.",
      "example": true
    }
  },
  "minProperties": 1,
  "maxProperties": 1,
  "additionalProperties": false
}
Delete selected cache keys
JSON
{ "cache_keys": [ "cached_response_550e8400" ] }
Delete all cached responses
JSON
{ "all": true }
Delete selected internal IDs (JWT only)
JSON
{ "ids": [ 123, 124, 125 ] }

Examples

Delete selected cache keys

Headers

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Request

JSON
{ "cache_keys": [ "cached_response_550e8400" ] }

Response

JSON
{ "body": { "success_count": 3, "error_count": 0, "errors": [], "deleted_count": 3, "message": "Successfully deleted 3 cached responses" } }

Delete all cached responses

Headers

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Request

JSON
{ "all": true }

Response

JSON
{ "body": { "success_count": 0, "error_count": 0, "errors": [], "deleted_count": 0, "message": "Successfully deleted 0 cached responses" } }

Delete selected internal IDs (JWT only)

Headers

JSON
{ "Authorization": "Bearer YOUR_RESPAN_API_KEY" }

Request

JSON
{ "ids": [ 123, 124, 125 ] }

Response

JSON
{ "body": { "success_count": 3, "error_count": 0, "errors": [], "deleted_count": 3, "message": "Successfully deleted 3 cached responses" } }

Responses

200

Cached responses were deleted synchronously.

application/json

Field Type Requirement Description and constraints
$ object and object Body
Canonical bulk result envelope plus delete-specific fields.
Reference: #/components/schemas/BulkDeleteResponse
$ (allOf 1) object Schema variant
Canonical result envelope for a bulk operation.
Reference: #/components/schemas/BulkOperationResponse
Example: {"success_count":1,"error_count":0,"errors":[]}
$ (allOf 1).success_count integer Required in parent
Number of items successfully processed.
Minimum: 0
$ (allOf 1).error_count integer Required in parent
Number of items that failed.
Minimum: 0
$ (allOf 1).errors array<object> Required in parent
Item-level failures, keyed by zero-based input index.
$ (allOf 1).errors[] object Array item
An item that failed during a bulk operation. index is zero-based and identifies the corresponding item in the request array.
Reference: #/components/schemas/BulkItemError
$ (allOf 1).errors[].index integer Required in parent
Zero-based index of the failed item in the submitted array.
Minimum: 0
$ (allOf 1).errors[].error string Required in parent
Error message for the failed item.
$ (allOf 2) object Schema variant
-
$ (allOf 2).deleted_count integer Required in parent
Number of resources matched and processed for deletion.
Minimum: 0
$ (allOf 2).message string Required in parent
Human-readable deletion result.

OpenAPI response schema

{
  "$ref": "#/components/schemas/BulkDeleteResponse"
}
Cached responses deleted
JSON
{ "success_count": 3, "error_count": 0, "errors": [], "deleted_count": 3, "message": "Successfully deleted 3 cached responses" }
No matching cache entries
JSON
{ "success_count": 0, "error_count": 0, "errors": [], "deleted_count": 0, "message": "Successfully deleted 0 cached responses" }

400

The selector is invalid, more than one selector was supplied, or API-key authentication was used with ids.

application/json

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

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}
Invalid selector combination
JSON
{ "non_field_errors": [ "Request body must contain exactly one of 'ids', 'cache_keys', or 'all'." ] }
Internal IDs used with an API key
JSON
{ "error": "Delete by 'ids' is only available via JWT. Use 'cache_keys' instead." }

403

The API key is missing, invalid or expired, or it can’t delete 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." }

422

The request contains more than 1,000 cache keys or IDs.

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": "Cannot process more than 1000 items at once." }

429

Rate limit exceeded.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-
retry_after integer Optional
Seconds to wait before retrying.
Minimum: 0

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    },
    "retry_after": {
      "type": "integer",
      "minimum": 0,
      "description": "Seconds to wait before retrying."
    }
  }
}
Example
JSON
{ "detail": "Rate limit exceeded", "retry_after": 30 }

OpenAPI source

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

OpenAPI operation

{
  "summary": "Delete cached responses in bulk",
  "operationId": "bulkDeleteCachedResponses",
  "tags": [
    "Caches"
  ],
  "description": "Delete cached responses using exactly one selector: `cache_keys`, `ids`, or `all: true`. Up to 1,000 keys or IDs can be deleted per request. `ids` uses internal integer IDs and is JWT-only; API-key clients should use `cache_keys` or `all`. Rate limit: 60 requests per minute per organization for API-key calls (shared across API keys) and per user for JWT calls.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "description": "Exactly one deletion mode is required.",
          "properties": {
            "cache_keys": {
              "type": "array",
              "description": "Cache keys to delete. Supported for API key and JWT authentication.",
              "items": {
                "type": "string"
              },
              "example": [
                "cached_response_550e8400"
              ],
              "minItems": 1,
              "maxItems": 1000
            },
            "ids": {
              "type": "array",
              "description": "Internal numeric cache entry IDs to delete. JWT only.",
              "items": {
                "type": "integer"
              },
              "example": [
                123,
                124,
                125
              ],
              "minItems": 1,
              "maxItems": 1000
            },
            "all": {
              "type": "boolean",
              "description": "Set to true to delete all cached responses for the current organization. The server rejects false.",
              "example": true
            }
          },
          "minProperties": 1,
          "maxProperties": 1,
          "additionalProperties": false
        },
        "examples": {
          "delete_by_cache_keys": {
            "summary": "Delete selected cache keys",
            "value": {
              "cache_keys": [
                "cached_response_550e8400"
              ]
            }
          },
          "delete_all": {
            "summary": "Delete all cached responses",
            "value": {
              "all": true
            }
          },
          "delete_by_ids": {
            "summary": "Delete selected internal IDs (JWT only)",
            "value": {
              "ids": [
                123,
                124,
                125
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Cached responses were deleted synchronously.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BulkDeleteResponse"
          },
          "examples": {
            "success": {
              "summary": "Cached responses deleted",
              "value": {
                "success_count": 3,
                "error_count": 0,
                "errors": [],
                "deleted_count": 3,
                "message": "Successfully deleted 3 cached responses"
              }
            },
            "noMatches": {
              "summary": "No matching cache entries",
              "value": {
                "success_count": 0,
                "error_count": 0,
                "errors": [],
                "deleted_count": 0,
                "message": "Successfully deleted 0 cached responses"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The selector is invalid, more than one selector was supplied, or API-key authentication was used with `ids`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          },
          "examples": {
            "invalidSelector": {
              "summary": "Invalid selector combination",
              "value": {
                "non_field_errors": [
                  "Request body must contain exactly one of 'ids', 'cache_keys', or 'all'."
                ]
              }
            },
            "idsRequireJwt": {
              "summary": "Internal IDs used with an API key",
              "value": {
                "error": "Delete by 'ids' is only available via JWT. Use 'cache_keys' instead."
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "The API key is missing, invalid or expired, or it can't delete 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."
          }
        }
      }
    },
    "422": {
      "description": "The request contains more than 1,000 cache keys or IDs.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              }
            }
          },
          "example": {
            "detail": "Cannot process more than 1000 items at once."
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "detail"
            ],
            "properties": {
              "detail": {
                "type": "string"
              },
              "retry_after": {
                "type": "integer",
                "minimum": 0,
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "example": {
            "detail": "Rate limit exceeded",
            "retry_after": 30
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ],
  "x-fern-examples": [
    {
      "name": "Delete selected cache keys",
      "request": {
        "cache_keys": [
          "cached_response_550e8400"
        ]
      },
      "response": {
        "body": {
          "success_count": 3,
          "error_count": 0,
          "errors": [],
          "deleted_count": 3,
          "message": "Successfully deleted 3 cached responses"
        }
      },
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    },
    {
      "name": "Delete all cached responses",
      "request": {
        "all": true
      },
      "response": {
        "body": {
          "success_count": 0,
          "error_count": 0,
          "errors": [],
          "deleted_count": 0,
          "message": "Successfully deleted 0 cached responses"
        }
      },
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    },
    {
      "name": "Delete selected internal IDs (JWT only)",
      "request": {
        "ids": [
          123,
          124,
          125
        ]
      },
      "response": {
        "body": {
          "success_count": 3,
          "error_count": 0,
          "errors": [],
          "deleted_count": 3,
          "message": "Successfully deleted 3 cached responses"
        }
      },
      "headers": {
        "Authorization": "Bearer YOUR_RESPAN_API_KEY"
      }
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "schemas": {
    "BulkDeleteResponse": {
      "description": "Canonical bulk result envelope plus delete-specific fields.",
      "allOf": [
        {
          "$ref": "#/components/schemas/BulkOperationResponse"
        },
        {
          "type": "object",
          "required": [
            "deleted_count",
            "message"
          ],
          "properties": {
            "deleted_count": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of resources matched and processed for deletion."
            },
            "message": {
              "type": "string",
              "description": "Human-readable deletion result."
            }
          }
        }
      ]
    },
    "BulkItemError": {
      "type": "object",
      "description": "An item that failed during a bulk operation. `index` is zero-based and identifies the corresponding item in the request array.",
      "required": [
        "index",
        "error"
      ],
      "properties": {
        "index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index of the failed item in the submitted array."
        },
        "error": {
          "type": "string",
          "description": "Error message for the failed item."
        }
      }
    },
    "BulkOperationResponse": {
      "type": "object",
      "description": "Canonical result envelope for a bulk operation.",
      "required": [
        "success_count",
        "error_count",
        "errors"
      ],
      "properties": {
        "success_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of items successfully processed."
        },
        "error_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of items that failed."
        },
        "errors": {
          "type": "array",
          "description": "Item-level failures, keyed by zero-based input index.",
          "items": {
            "$ref": "#/components/schemas/BulkItemError"
          }
        }
      },
      "example": {
        "success_count": 1,
        "error_count": 0,
        "errors": []
      }
    }
  },
  "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"
      }
    }
  }
}