Query Syntax
Sift has two separate filter DSLs that look similar but aren't interchangeable. Which one applies depends on where you're filtering.
At a glance
Web app search bar ?f=, MCP search, saved-search criteria | Advanced Search DSL |
The public REST API's GET /v0/action/list?filter= | simple gateway DSL |
Both use + for AND | ✅ |
The ro shorthand means something different in each DSL | ⚠️ see below |
| Chain conditions, no spaces in the raw string | ✅ |
Advanced Search DSL
This is the one you'll use most - it powers the web app search bar's ?f= parameter, saved searches, the MCP search tool, and analytics. It supports more than the simple DSL below: comparisons, ranges, lists, OR, and grouping.
| Pattern | Meaning |
|---|---|
field=value / field!=value | Equals / not equals |
field>value field>=value field<value field<=value | Numeric or date comparison |
field~value / field!~value | Contains / does not contain |
field^=value / field$=value | Starts with / ends with |
field=min..max | Range |
field=v1,v2 | Any of a list of values |
expr1+expr2 | AND |
expr1|expr2 | OR |
(expr) | Grouping |
Common fields (canonical name - some have short aliases): source (src), status (st), channelId (ch), queueId (q), tagId (tag), keyword (kw), sentiment (sent), responded (hasResponse), relevance (rel), isRoot (ro, rootRecord).
ro means isRoot here, not "responded." If you want to filter on whether an action has been responded to, use responded directly - ro doesn't alias it in this DSL.
Examples
Open Discord items:
source=discord+status=openBilling-queue items that have not been responded to:
queue=billing+responded!=trueItems with a score of at least 50, from either Twitter or Instagram:
source=twitter|instagram+postScore>=50Using it in the web app
Append the ?f= parameter to any search URL:
https://app.getsift.ai/app/search?f=source%3Ddiscord%2Bstatus%3DopenYou can also type filters directly in the search bar using the same syntax.
Simple gateway DSL
GET /v0/action/list on the public REST API uses a smaller, separate DSL - it only supports = (equals, or "one of" for a comma-separated list) and != (not-equals), chained with + for AND. No comparisons, ranges, OR, or grouping.
| Short form | Long form |
|---|---|
src | source |
st | status |
ch | channel |
q | queue |
tag | userTag |
kw | keyword |
agent | assignee |
ro | responded |
In this DSL, ro does mean responded - the opposite of its meaning in the Advanced Search DSL above. Don't assume the two are interchangeable just because the syntax looks similar.
Example
Billing-queue items that have not been responded to, via the REST API:
GET https://api.getsift.ai/v0/action/list?filter=q%3Dbilling%2Bro%21%3Dtrue
X-API-Key: sk_live_your_key_hereURL-encode the filter string when embedding it in a URL: = becomes %3D, + becomes %2B, ! becomes %21.