Filters

Saved filters are named, reusable criteria for a Dataset. A filter belongs to a user or team and is either private to its owner or public (visible to everyone who can see the Dataset).

A filter row has two payload columns, both stored verbatim:

Column	What it holds
filter	An Elasticsearch query fragment (term, range, bool, …) applied to searches when the filter is used
filterConfig	The web client's filter-builder state, so the UI can re-open the filter for editing. API-created filters can leave it null

GET /api/datasets/{datasetId}/filters

Get saved filters for a Dataset: public ones plus your own private ones.

Authentication: Required

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset UUID or ownerId:slug natural id

List saved filters for a DatasetGET /api/datasets/admin:northwind-orders/filters

You see public filters plus your own private ones.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/filters"
    }
  },
  "start": 0,
  "count": 1,
  "total": 1,
  "_embedded": {
    "inf:filter": [
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/filters/00000000-0000-4000-8000-000000000001"
          }
        },
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "USA Orders",
        "useDefaultName": null,
        "filter": {
          "term": {
            "ShipCountry": "USA"
          }
        },
        "filterConfig": null,
        "ownerId": "admin",
        "public": true,
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "tenant": "acme",
        "datasetId": "00000000-0000-4000-8000-000000000002"
      }
    ]
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

ETag Support: Based on dataset_filter table changes.

---

POST /api/datasets/{datasetId}/filters

Create a saved filter.

Authentication: Required

Permission: None beyond read access to the Dataset; anyone who can see a Dataset can save filters on it.

Request Body:

Field	Type	Required	Description
name	string	No	Display name
filter	object	No	Elasticsearch query fragment
filterConfig	object	No	Client filter-builder state
public	boolean	No	Visible to everyone (default false: private to you)
useDefaultName	boolean	No	Client hint that the name was auto-generated

ownerId is always set to the calling user; to hand the filter to a team, transfer it via the owner endpoint afterwards.

Response: 201 Created with a Location header.

Create a saved filterPOST /api/datasets/admin:northwind-orders/filters

filter is an Elasticsearch query fragment applied to searches; filterConfig is the web client's filter-builder state, stored verbatim. ownerId is always set to the calling user. public: true makes the filter visible to everyone with access to the Dataset.

Request body

{
  "name": "USA Orders",
  "public": true,
  "filter": {
    "term": {
      "ShipCountry": "USA"
    }
  }
}

Response · 201

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/filters/00000000-0000-4000-8000-000000000002"
    }
  },
  "id": "00000000-0000-4000-8000-000000000002",
  "tenant": "acme",
  "name": "USA Orders",
  "public": true,
  "filter": {
    "term": {
      "ShipCountry": "USA"
    }
  },
  "datasetId": "00000000-0000-4000-8000-000000000001",
  "ownerId": "admin",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "useDefaultName": null,
  "filterConfig": null,
  "_altid": null
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

GET /api/datasets/{datasetId}/filters/{id}

Get a single saved filter.

Authentication: Required

Get a saved filterGET /api/datasets/admin:northwind-orders/filters/00000000-0000-4000-8000-000000000001

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/filters/00000000-0000-4000-8000-000000000001"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "name": "USA Orders",
  "useDefaultName": null,
  "filter": {
    "term": {
      "ShipCountry": "USA"
    }
  },
  "filterConfig": null,
  "ownerId": "admin",
  "public": true,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "datasetId": "00000000-0000-4000-8000-000000000002"
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

PUT /api/datasets/{datasetId}/filters/{id}

Update a saved filter.

Authentication: Required

Permission: filter:edit (Data Wizard or above relative to the filter's owner: your own filters, or team filters where you hold Data Wizard+)

Update a saved filterPUT /api/datasets/admin:northwind-orders/filters/00000000-0000-4000-8000-000000000001

Request body

{
  "name": "USA Orders",
  "public": true,
  "filter": {
    "bool": {
      "filter": [
        {
          "term": {
            "ShipCountry": "USA"
          }
        },
        {
          "range": {
            "Freight": {
              "gte": 50
            }
          }
        }
      ]
    }
  }
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/filters/00000000-0000-4000-8000-000000000001"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "name": "USA Orders",
  "useDefaultName": null,
  "filter": {
    "bool": {
      "filter": [
        {
          "term": {
            "ShipCountry": "USA"
          }
        },
        {
          "range": {
            "Freight": {
              "gte": 50
            }
          }
        }
      ]
    }
  },
  "filterConfig": null,
  "ownerId": "admin",
  "public": true,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "datasetId": "00000000-0000-4000-8000-000000000002"
}

Captured from the API examples test suite; ids and timestamps are normalized.

Privacy and ownership

The public flag is updated through this same PUT. The client-facing changePrivacy permission flag signals who should see that control, but the route itself enforces filter:edit. ownerId changes go through the owner endpoint below.

---

DELETE /api/datasets/{datasetId}/filters/{id}

Delete a saved filter.

Authentication: Required

Permission: filter:edit (same rule as PUT)

Delete a saved filterDELETE /api/datasets/admin:northwind-orders/filters/00000000-0000-4000-8000-000000000001

Responds 200 with an empty body.

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.

---

GET /api/datasets/{datasetId}/filters/{id}/owner

Get the filter's owner: the principal row with the user (or team) embedded.

Authentication: Required

Get a filter's ownerGET /api/datasets/admin:northwind-orders/filters/00000000-0000-4000-8000-000000000001/owner

The owner principal, with the user (or team) embedded.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/filters/00000000-0000-4000-8000-000000000001/owner"
    }
  },
  "id": "admin",
  "userId": "admin",
  "teamId": null,
  "tenant": "acme",
  "_embedded": {
    "inf:user": {
      "_links": {
        "self": {
          "href": "https://informer.example.com/api/users/admin"
        },
        "inf:memberships": {
          "href": "https://informer.example.com/api/users/admin/memberships"
        },
        "inf:avatar-upload": {
          "href": "https://informer.example.com/api/users/admin/_upload/{uploadId}/avatar-upload",
          "templated": true
        },
        "inf:password": {
          "href": "https://informer.example.com/api/users/admin/password"
        },
        "inf:feed": {
          "href": "https://informer.example.com/api/users/admin/feed"
        },
        "inf:viewed-feed": {
          "href": "https://informer.example.com/api/users/admin/_markFeedViewed"
        },
        "inf:superuser": {
          "href": "https://informer.example.com/api/users/admin/superuser"
        }
      },
      "permissions": {
        "changeDomain": false,
        "changeProfile": true,
        "changePassword": true,
        "delete": false,
        "edit": true,
        "reassign": true,
        "superuser": true,
        "enable": true,
        "changeTheme": true,
        "lock": true,
        "setGlobalPermissions": true,
        "manageLogin": true
      },
      "domain": "local",
      "username": "admin",
      "displayName": "acme Administrator",
      "familyName": "Administrator",
      "givenName": "acme",
      "middleName": null,
      "email": null,
      "data": null,
      "superuser": true,
      "timezone": "America/New_York",
      "settings": {
        "log": {
          "log": false,
          "info": false,
          "warn": false,
          "debug": false,
          "error": true,
          "remote": false
        }
      },
      "enabled": true,
      "source": null,
      "sourceId": null,
      "lastViewedFeed": null,
      "tenant": "acme",
      "globalPermissions": {
        "ai": false,
        "jobCreation": true,
        "viewAllTeams": true,
        "viewAllUsers": true,
        "painlessScriptCreation": true
      },
      "userFields": {},
      "locked": false,
      "lockedAt": null,
      "loginAttempts": 0,
      "passwordSetAt": "2026-01-15T16:20:00.000Z",
      "passwordExpiresAt": "2026-01-15T16:20:00.000Z",
      "forgotPasswordRequestTime": null,
      "mfa": null,
      "mfaConfig": {},
      "aiMessage": null,
      "aiConsent": false,
      "hasSharedDatasources": false,
      "createdAt": "2026-01-15T16:20:00.000Z",
      "updatedAt": "2026-01-15T16:20:00.000Z",
      "initials": "NA",
      "colorIndex": 4,
      "avatarColor": {
        "background": "#81C784",
        "text": "#1B5E20"
      },
      "managesPassword": true
    }
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

PUT /api/datasets/{datasetId}/filters/{id}/owner

Transfer the filter to another user or team.

Authentication: Required

Permission: filter:edit

Request Body:

The payload identifies the new owner principal: { "id": "<username or team id>" }. An unknown principal answers 400.

Response: the updated filter.

Transfer a filter to another ownerPUT /api/datasets/admin:northwind-orders/filters/00000000-0000-4000-8000-000000000001/owner

The payload identifies the new owner principal by id: a username or a team id. The response is the updated filter.

Request body

{
  "id": "everett"
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/filters/00000000-0000-4000-8000-000000000001/owner"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "name": "USA Orders",
  "useDefaultName": null,
  "filter": {
    "bool": {
      "filter": [
        {
          "term": {
            "ShipCountry": "USA"
          }
        },
        {
          "range": {
            "Freight": {
              "gte": 50
            }
          }
        }
      ]
    }
  },
  "filterConfig": null,
  "ownerId": "everett",
  "public": true,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "datasetId": "00000000-0000-4000-8000-000000000002"
}

Captured from the API examples test suite; ids and timestamps are normalized.

---

GET /api/dataset-filters

Get saved filters across Datasets in one call. The response is a plain array (not HAL).

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
datasets	string	No	One or more Dataset ids or natural ids (repeat the parameter for several). Without it, all filters you can see are returned

Publishers and above see every filter; other users see public filters plus their own.

List saved filters across DatasetsGET /api/dataset-filters?datasets=admin:northwind-orders

Plain array (not HAL). datasets accepts one or more Dataset ids or natural ids. Without it, all filters you can see are returned.

Response · 200

[
  {
    "datasetId": "00000000-0000-4000-8000-000000000001",
    "id": "00000000-0000-4000-8000-000000000002",
    "name": "USA Orders",
    "useDefaultName": null,
    "filter": {
      "bool": {
        "filter": [
          {
            "term": {
              "ShipCountry": "USA"
            }
          },
          {
            "range": {
              "Freight": {
                "gte": 50
              }
            }
          }
        ]
      }
    },
    "filterConfig": null,
    "public": true,
    "ownerId": "admin",
    "createdAt": "2026-01-15T16:20:00.000Z",
    "updatedAt": "2026-01-15T16:20:00.000Z",
    "permissions": {
      "changePrivacy": true,
      "edit": true
    }
  }
]

Captured from the API examples test suite; ids and timestamps are normalized.

ETag Support: Based on dataset_filter table changes.

---

POST /api/dataset-field-report-access

Toggle whether Reports built on a Dataset may expose its fields to consumers who cannot read the Dataset itself.

Authentication: Required

Permission: dataset:share on every Dataset in the payload (superuser, or Publisher and above on the owning team)

Request Body:

An object keyed by Dataset UUID with boolean values. Any id you cannot read answers 404 for the whole request.

Response: the resulting datasetFieldReportAccess value per Dataset.

Toggle field access for ReportsPOST /api/dataset-field-report-access

Keys are Dataset UUIDs. true lets Reports built on the Dataset expose its fields to consumers who cannot read the Dataset itself. Requires share permission on every Dataset in the payload.

Request body

{
  "00000000-0000-4000-8000-000000000001": true
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/dataset-field-report-access"
    }
  },
  "00000000-0000-4000-8000-000000000001": true
}

Captured from the API examples test suite; ids and timestamps are normalized.

Behavior:

• true: Dataset fields become visible in Report contexts regardless of Dataset sharing
• false (default): Report consumers see fields only if Dataset sharing grants them read access