Skip to main content
Two capabilities share this surface:
  • Filter language — narrow a list of items by field, property, tag, or edge.
  • Full-text search — find items by keyword across their content.
Both use the same filter parameter grammar. Both return paginated item lists.

​
Listing items

GET /items accepts type / state / tag / tier / edge / backref / filter narrowing plus pagination. A few characteristic examples:
The full parameter list and response shape are in the List items endpoint reference. A few semantics worth knowing:
  • type — matches subtypes via inheritance. type=core.media returns core.media.book, core.media.article, etc.
  • since and until — operate on the item’s effective time (timestamp, falling back to created_at), not updated_at.
  • include — off by default to keep list responses lean. Pass edges or metadata to hydrate.
  • tier — library, feed, or omitted (returns both slices).
Cursors are stable within the cursor’s lifetime (24h typical) — concurrent writes don’t shift pages already returned. Paginate by passing cursor back as a query parameter.

​
Full-text search

GET /search accepts q plus the same filter parameters as /items:
Index scope: all textual properties of the item (body, title, description, etc.) plus tags. Ranking by relevance, with recency boost configurable per tenant. q narrows by text match, filter parameters narrow further. tags accepts a comma-separated list with AND semantics — items must have every listed tag.
Result ordering is stable; the absolute score value isn’t guaranteed across index rebuilds. Rely on order, not magnitude.

​
Filter language

The filter parameter accepts expressions over system fields, properties, and metadata.

​
Grammar

System fields recognized: id, type, source, timestamp, created_at, updated_at, tier, device, version.

​
Examples

​
Operators

​
Combining conditions

Conditions join with AND or OR. You can’t mix AND and OR within a single expression — use one or the other. For complex logic, break into multiple queries or chain via a client-side join.

​
Edge shorthand

edge[X]=Y as a query parameter is equivalent to filter=edge[X] eq "Y". Both return items that have an outbound edge of type X targeting Y. Use the shorthand when only one edge clause is needed. backref[X]=Y is the inbound equivalent.

​
Quoting and escaping

String values in the filter language use double quotes: "George Orwell". Double quotes inside a string are escaped with a backslash. The filter query parameter value must be URL-encoded in the request line.

​
Paginating search results

Search results use limit and offset pagination rather than cursors:
Offset pagination is stable for the lifetime of a given query.