---
title: "Create Filter Spec"
method: POST
path: "/api/v1/filters"
tags: ["filters"]
---

# Create Filter Spec

`POST /api/v1/filters`

Create (or return existing) FilterSpec for the given filter shape.

Idempotent: repeated POSTs with the same canonical body return the same
``filter_id``. Sliding TTL means downstream reads keep the spec alive.

## Request body

- FilterSpecRequest — Payload accepted by ``POST /filters``. All four fields participate in the canonical hash that derives the ``filter_id`` — same shape produces the same ID, idempotent under repeat POST.
  - `filterModel` object — AG Grid native filter model (Record<colId, FilterCondition>).
  - `geometry` object, nullable — Optional GeoJSON polygon scoping the filter.
  - `searchText` string, nullable — Optional free-text search applied across searchable columns.
  - `favoritesOnly` boolean — Restrict matching rows to the user's favorites.

## Response `200`

Successful Response

- FilterSpecResponse — Response returned by ``POST /filters`` and the share-mode twin. ``expires_at`` reflects the current sliding TTL window. Every subsequent consumer read (tile request / paginated fetch / etc.) refreshes the window, so an active session never sees the spec expire mid-flight.
  - `filterId` string, uuid, required
  - `expiresAt` string, date-time, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/maia-analytics/maia-api/revisions/0c94a4b5a00e/schema)