Skip to main content
POST
Convert natural language to filters

Authorizations

Authorization
string
header
required

Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>.

Body

application/json

Convert a natural-language query into an Octolens filter object.

query
string
required

Natural-language description of what the user wants to see.

Required string length: 1 - 1000
Example:

"only negative tweets about pricing from the last 7 days"

target
enum<string>

Which filter contract to return (default mentions). mentions returns the flat filter map accepted by POST /api/v2/mentions filters. feed returns the SimpleFilters/AdvancedFilters shape accepted verbatim by the feed endpoints (POST /api/v2/feeds / PATCH /api/v2/feeds/{id}) — the two contracts are not interchangeable.

Available options:
mentions,
feed

Response

200 response

Filter object generated from a natural-language query. Client applies filters to the feed and shows explanation to the user.

filters
object
required

Generated filter object, in the contract selected by target: the flat mentions filter map (default) or a feed SimpleFilters/AdvancedFilters shape (target: "feed"). null when the query is ambiguous or matches everything. Use isAdvanced to determine whether it's the simple or advanced shape.

isAdvanced
boolean
required

If true, filters is an AdvancedFilters shape (AND/OR groups). Otherwise it's a SimpleFilters (flat AND list).

limit
integer
required

Requested page size — preserved from currentLimit unless the user asked to change it.

Required range: -9007199254740991 <= x <= 9007199254740991
includeAll
boolean
required

Whether to include low-relevance posts.

view
integer | null
required

View id the AI resolved the query against (if the user referenced a view by name). null otherwise.

Required range: -9007199254740991 <= x <= 9007199254740991
explanation
string
required

Plain-English summary of what the filter will match — shown in the UI.