Skip to main content
POST
/
api
/
v1
/
context
/
filters
Create a filter context item
curl --request POST \
  --url https://api.staging.getmodus.com/api/v1/context/filters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "active_subscribers",
  "description": "Subscribers whose status is active and last seen within 30 days.",
  "expr": "${subscribers.status} = 'active' AND ${subscribers.last_seen_at} > NOW() - INTERVAL '30 days'"
}
EOF
{
  "contextItemId": "7a3f9d2c-1111-4000-a000-000000000abc",
  "kind": "note",
  "s3Key": "context_notes/7a3f9d2c.../Q3_churn_analysis.md",
  "title": "Q3 churn analysis"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Filter name.

Example:

"active_subscribers"

​
description
string
required

Human description.

Example:

"Subscribers whose status isactiveandlast_seen_at< 30d ago."

​
expr
string
required

Filter expression.

Example:

"${subscribers.status} = 'active' AND ${subscribers.last_seen_at} > NOW() - INTERVAL '30 days'"

​
synonyms
string[]

Optional synonyms used for fuzzy matching.

Response

​
contextItemId
string
required

UUID of the newly-created context item. Use it on subsequent GET / PATCH / DELETE calls.

Example:

"7a3f9d2c-1111-4000-a000-000000000abc"

​
kind
enum<string>
required

Kind of context item created.

Available options:
note,
saved_query,
link,
dimension,
fact,
metric,
filter
Example:

"note"

​
s3Key
string | null

Tenant S3 key for the raw content blob (notes, saved queries, links). Null for kinds without S3 backing.

Example:

"context_notes/7a3f9d2c.../Q3_churn_analysis.md"

​
title
string | null

Resolved title for the created item. Null for kinds without a title field.

Example:

"Q3 churn analysis"