Skip to content

Canonical filter operators: terse tokens + isEmpty/notEmpty (long-form aliases deprecated on /v0/profiles) #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yosriady merged 3 commits into from
Jul 24, 2026
Merged

Canonical filter operators: terse tokens + isEmpty/notEmpty (long-form aliases deprecated on /v0/profiles) #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6c55f52
docs: canonical filter operators + isEmpty/notEmpty (v0/profiles alia…
yosriady Jul 24, 2026
32da1e6
Terse canonical operators; long forms deprecated-but-accepted on /v0/…
yosriady Jul 24, 2026
20c53a2
Team Settings nav is 'API', not 'API Keys', in openapi descriptions
yosriady Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 36 additions & 24 deletions api/boards/create-chart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,21 +143,27 @@

| `op` | SQL equivalent | Notes |
| ------------ | ---------------------- | ----------------------------------------------------- |
| `equals` | `= 'value'` | Exact match |
| `notEquals` | `!= 'value'` | Inverse match |
| `eq` | `= 'value'` | Exact match |
| `neq` | `!= 'value'` | Inverse match |
| `in` | `IN (...)` | Pipe-delimited value: `"metamask\|rainbow\|coinbase"` |
| `notIn` | `NOT IN (...)` | Pipe-delimited value |
| `nin` | `NOT IN (...)` | Pipe-delimited value |
| `gt` | `> value` | Numeric comparison |
| `gte` | `>= value` | Numeric comparison |
| `lt` | `< value` | Numeric comparison |
| `lte` | `<= value` | Numeric comparison |
| `startsWith` | `startsWith(col, 'v')` | String prefix |
| `endsWith` | `endsWith(col, 'v')` | String suffix |
| `includes` | `like '%v%'` | Substring match |
| `contains` | `like '%v%'` | Substring match |

Check warning on line 156 in api/boards/create-chart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/boards/create-chart.mdx#L156 

Did you really mean 'Substring'?
| `notEmpty` | `col != ''` | Value-less existence check; `value` is ignored |
| `isEmpty` | `col = ''` | Value-less existence check; `value` is ignored |

<Tip>
For `in` and `notIn`, join multiple values with a pipe `|`. Escape a literal
pipe with `\|` and a literal backslash with `\\`.
For `in` and `nin`, join multiple values with a pipe `|`. Escape a literal
pipe with `\|` and a literal backslash with `\\`. The legacy numeric long
forms (`greater`, `greaterOrEqual`, `less`, `lessOrEqual`) are deprecated
aliases for `gt` / `gte` / `lt` / `lte` and remain accepted. `notEmpty` and
`isEmpty` are rejected on the numeric event columns `volume` / `revenue` /
`points`.
</Tip>

### `settings` for Funnel Charts
Expand Down Expand Up @@ -208,7 +214,7 @@

#### With per-step property filters

Filter step 2 to MetaMask wallets on Ethereum mainnet:

Check warning on line 217 in api/boards/create-chart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/boards/create-chart.mdx#L217 

Did you really mean 'mainnet'?

```json
{
Expand All @@ -221,8 +227,8 @@
{
"type": "event",
"event": "connect",
"rdns": { "op": "equals", "value": "io.metamask" },
"chain_id": { "op": "equals", "value": "1" }
"rdns": { "op": "eq", "value": "io.metamask" },
"chain_id": { "op": "eq", "value": "1" }
},
{ "type": "event", "event": "transaction" }
],
Expand Down Expand Up @@ -266,7 +272,7 @@
{
"type": "event",
"event": "page",
"device": { "op": "equals", "value": "mobile" }
"device": { "op": "eq", "value": "mobile" }
},
{
"type": "event",
Expand Down Expand Up @@ -333,7 +339,7 @@
| Field | Type | Description |
| ------- | ---------------- | ------------------------------------------------------------------------ |
| `field` | string | User property (e.g. `device`, `browser`, `os`, `utm_source`, `location`) |
| `op` | string | Comparison operator (same set as `StepFilterCondition.op`) |
| `op` | string | Comparison operator (same set as `StepFilterCondition.op`, minus the substring operators `startsWith` / `endsWith` / `contains`) |

Check warning on line 342 in api/boards/create-chart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/boards/create-chart.mdx#L342 

Did you really mean 'substring'?
| `value` | string \| number | Value to compare against |

```json
Expand All @@ -345,8 +351,8 @@
"settings": {
"retentionFilter": { "type": "event", "event": "transaction" },
"retentionUserFilters": [
{ "field": "device", "op": "equals", "value": "desktop" },
{ "field": "utm_source", "op": "notEquals", "value": "direct" }
{ "field": "device", "op": "eq", "value": "desktop" },
{ "field": "utm_source", "op": "neq", "value": "direct" }
]
}
}
Expand Down Expand Up @@ -550,21 +556,27 @@

| `op` | SQL equivalent | Notes |
| ------------ | ---------------------- | ----------------------------------------------------- |
| `equals` | `= 'value'` | Exact match |
| `notEquals` | `!= 'value'` | Inverse match |
| `eq` | `= 'value'` | Exact match |
| `neq` | `!= 'value'` | Inverse match |
| `in` | `IN (...)` | Pipe-delimited value: `"metamask\|rainbow\|coinbase"` |
| `notIn` | `NOT IN (...)` | Pipe-delimited value |
| `nin` | `NOT IN (...)` | Pipe-delimited value |
| `gt` | `> value` | Numeric comparison |
| `gte` | `>= value` | Numeric comparison |
| `lt` | `< value` | Numeric comparison |
| `lte` | `<= value` | Numeric comparison |
| `startsWith` | `startsWith(col, 'v')` | String prefix |
| `endsWith` | `endsWith(col, 'v')` | String suffix |
| `includes` | `like '%v%'` | Substring match |
| `contains` | `like '%v%'` | Substring match |

Check warning on line 569 in api/boards/create-chart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/boards/create-chart.mdx#L569 

Did you really mean 'Substring'?
| `notEmpty` | `col != ''` | Value-less existence check; `value` is ignored |
| `isEmpty` | `col = ''` | Value-less existence check; `value` is ignored |

<Tip>
For `in` and `notIn`, join multiple values with a pipe `|`. Escape a literal
pipe with `\|` and a literal backslash with `\\`.
For `in` and `nin`, join multiple values with a pipe `|`. Escape a literal
pipe with `\|` and a literal backslash with `\\`. The legacy numeric long
forms (`greater`, `greaterOrEqual`, `less`, `lessOrEqual`) are deprecated
aliases for `gt` / `gte` / `lt` / `lte` and remain accepted. `notEmpty` and
`isEmpty` are rejected on the numeric event columns `volume` / `revenue` /
`points`.
</Tip>

### `settings` for Funnel Charts
Expand Down Expand Up @@ -615,7 +627,7 @@

#### With per-step property filters

Filter step 2 to MetaMask wallet connections on Ethereum mainnet:

Check warning on line 630 in api/boards/create-chart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/boards/create-chart.mdx#L630 

Did you really mean 'mainnet'?

```json
{
Expand All @@ -628,8 +640,8 @@
{
"type": "event",
"event": "connect",
"rdns": { "op": "equals", "value": "io.metamask" },
"chain_id": { "op": "equals", "value": "1" }
"rdns": { "op": "eq", "value": "io.metamask" },
"chain_id": { "op": "eq", "value": "1" }
},
{ "type": "event", "event": "transaction" }
],
Expand Down Expand Up @@ -673,7 +685,7 @@
{
"type": "event",
"event": "page",
"device": { "op": "equals", "value": "mobile" }
"device": { "op": "eq", "value": "mobile" }
},
{
"type": "event",
Expand Down Expand Up @@ -740,7 +752,7 @@
| Field | Type | Description |
| ------- | ---------------- | ------------------------------------------------------------------------ |
| `field` | string | User property (e.g. `device`, `browser`, `os`, `utm_source`, `location`) |
| `op` | string | Comparison operator (same set as `StepFilterCondition.op`) |
| `op` | string | Comparison operator (same set as `StepFilterCondition.op`, minus the substring operators `startsWith` / `endsWith` / `contains`) |

Check warning on line 755 in api/boards/create-chart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/boards/create-chart.mdx#L755 

Did you really mean 'substring'?
| `value` | string \| number | Value to compare against |

```json
Expand All @@ -752,8 +764,8 @@
"settings": {
"retentionFilter": { "type": "event", "event": "transaction" },
"retentionUserFilters": [
{ "field": "device", "op": "equals", "value": "desktop" },
{ "field": "utm_source", "op": "notEquals", "value": "direct" }
{ "field": "device", "op": "eq", "value": "desktop" },
{ "field": "utm_source", "op": "neq", "value": "direct" }
]
}
}
Expand Down
2 changes: 1 addition & 1 deletion api/idempotency.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: 'Idempotency'
description: 'Use the Idempotency-Key header to safely retry POST/PUT/PATCH/DELETE requests on the Formo Public API without double-creating or double-charging.'

Check warning on line 3 in api/idempotency.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/idempotency.mdx#L3 

Did you really mean 'Idempotency'?

Check warning on line 3 in api/idempotency.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/idempotency.mdx#L3 

Use 'formo' instead of 'Formo'.
icon: rotate
iconType: solid
---

Public unsafe methods (POST / PUT / PATCH / DELETE) on the Alerts, Charts, Contracts, Segments, and Import APIs honour an optional `Idempotency-Key` header. When present, Formo de-duplicates retries so a flaky network or a crashed client never causes a double-write.

Check warning on line 8 in api/idempotency.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/idempotency.mdx#L8 

Did you really mean 'APIs'?

Check warning on line 8 in api/idempotency.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/idempotency.mdx#L8 

Use 'formo' instead of 'Formo'.

The header is **opt-in** - omit it and every request is processed independently.

Expand Down Expand Up @@ -49,14 +49,14 @@

### Cache outage

If the idempotency cache is unavailable, the request runs without caching - a cache outage doesn't block writes. Concurrent retries during such an outage may double-execute; the contract is best-effort.

Check warning on line 52 in api/idempotency.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/idempotency.mdx#L52 

Did you really mean 'idempotency'?

## Recommended client patterns

1. **Generate a fresh UUID v4 per logical operation.** Don't reuse keys across different actions, even if the body looks similar.
2. **Persist the key before the first attempt.** Save it to disk / DB before calling the API so an in-flight crash doesn't lose it. On restart, retry with the same key.
3. **Scope to a single workspace.** Two API keys for *different* projects can safely share an idempotency key - but don't rely on that; scope per workspace anyway.

Check warning on line 58 in api/idempotency.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/idempotency.mdx#L58 

Did you really mean 'idempotency'?
4. **Pair with retry-with-backoff for `429` / `503` / `5xx`.** Idempotency makes those safe to replay.

Check warning on line 59 in api/idempotency.mdx

View check run for this annotation

Mintlify / Mintlify Validation (formo) - vale-spellcheck

api/idempotency.mdx#L59 

Did you really mean 'Idempotency'?
5. **Maximum length: 255 characters.** Use a UUID v4 (36 chars) or any random ≤255-char string.

## Examples
Expand All @@ -72,7 +72,7 @@
"name": "Daily revenue drop",
"trigger_type": "event",
"trigger_filters": [
{ "name": "event", "operator": "equals", "value": "transaction" }
{ "name": "event", "operator": "eq", "value": "transaction" }
],
"recipient": [{ "type": "webhook", "value": ["https://myapp.com/formo-webhook"] }]
}'
Expand Down
Loading