Quick filters

GET /quick-filters

List the organization's saved quick filters, the one-click presets that sit above each list screen.

Requires the settings:read permission.

Query Parameters

limitnumber

The number of records to return.

cursorstring

A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

sortname | -name | createdAt | -createdAt

The sort order. Prefix a field with - to sort descending. Defaults to -createdAt.

filterstring

A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, type, name, createdAt. See Filtering for the syntax.

Request
curl \
  "https://api.cascade.dev/quick-filters" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
Response
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "customers",
      "name": "string",
      "filter": "...",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "nextCursor": "string"
}

POST /quick-filters

Create a quick filter. The filter document is validated against the fields its screen allows, so an unknown field is rejected up front. Triggers the quickFilter.created webhook.

Requires the settings:write permission.

Body Parameters

dataobjectrequired

The quick filter to create.

Request
curl \
  -X POST \
  "https://api.cascade.dev/quick-filters" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "type": "customers",
    "name": "string",
    "filter": "..."
  }
}'
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

GET /quick-filters/{id}

Get a single quick filter by ID.

Requires the settings:read permission.

Path Parameters

idstring (uuid)required

The ID of the quick filter.

Request
curl \
  "https://api.cascade.dev/quick-filters/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

PUT /quick-filters/{id}

Rename a quick filter or change what it matches. Its screen cannot be changed. Triggers the quickFilter.updated webhook.

Requires the settings:write permission.

Path Parameters

idstring (uuid)required

The ID of the quick filter to update.

Body Parameters

dataobjectrequired

The fields to update.

Request
curl \
  -X PUT \
  "https://api.cascade.dev/quick-filters/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "name": "string",
    "filter": "..."
  }
}'
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

DELETE /quick-filters/{id}

Delete a quick filter. The records it matched are untouched. Triggers the quickFilter.deleted webhook.

Requires the settings:write permission.

Path Parameters

idstring (uuid)required

The ID of the quick filter to delete.

Request
curl \
  -X DELETE \
  "https://api.cascade.dev/quick-filters/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "customers",
  "name": "string",
  "filter": "...",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}