Syften Documentation

Syften is configured as a set of filters. A filter is a search rule: the words, phrases, domains, authors, sites, and exclusions that decide whether an incoming post or comment is interesting. Add one filter per thing you want to watch, such as your product name, a competitor, a domain, or a buying-intent phrase. Syften checks new items from supported communities against those filters and sends matches to your configured destinations.

Start with simple filters and preview the matches. If a filter is too broad, make it more specific: restrict it to one community with site:, watch only posts or comments with type:, follow a specific account with author:, require a language with lang:, or use $accept: as an AI post-filter. After the matching rules are right, configure delivery. Tags let different filters send matches to different Slack channels, email addresses, RSS feeds, API clients, or webhooks.

Reference

Literal text matching

By default, Syften uses fuzzy matching. For example, the filter "cat and" will match text like I bought a cat, and so... and I have a cat and a dog, but not I had a copycat and he.... That is because special characters are ignored and word boundary logic is applied.

The same applies to punctuation inside keywords. The filter a,b-c will match, among other things, the text A... b!c. This is what you would expect from a Google search.

However, Syften is not Google and does not need to instantly search through terabytes of data. We're only filtering once, through live data, delivering the matches and discarding the rest. This allows us some more CPU-heavy operations, like matching special characters. If you want to match special characters, as a text editor search would, surround your filter with backticks, like so: `a,b-c`.

The archive does not support the literal text matching operator.

Domain name matching

Domains are treated specially. A positive domain keyword like example.com or "example.com" will match things like example.com, www.example.com, and example[.]com, but not plain prose like example com or unrelated longer domains like someother-example.com.

Bare domains are usually the simplest choice, but the extra handling applies to positive quoted domains too. That extra handling does not apply to negated domains. A negated filter like NOT example.com behaves like an ordinary fuzzy negation, so it can also exclude things like example com or someother-example.com.

The site: operator

The site: operator performs a case-insensitive substring match on the URL of the matched item. Of course, the site must be one of the communities Syften supports.

It is usually best to end the site with a trailing slash. Otherwise the results might be surprising. For example, site:reddit.com/r/cat will also match URLs such as reddit.com/r/catapult. In this example, the proper syntax would be: site:reddit.com/r/cat/.

Multiple site: operators can be placed on one line, and they will be logically ORed together. For example, you can match several subreddits with:

site:reddit.com/r/saas/ site:reddit.com/r/startups/ site:reddit.com/r/EntrepreneurRideAlong/

Language detection

Examples

mailchimp NOT `?utm_source=mailchimp`

site:news.ycombinator.com type:post title:secur*

site:reddit.com/r/msp site:mspvendor.slack.com windows

"wordpress theme*" `?` NOT `https://`

example.com

syften NOT lang:sv

$tag:customers is Syften metadata used for delivery routing. Tags are not searchable terms by themselves.

Use tags when you want to organize filters or route different matches to different email addresses and Slack channels. Multiple tags are allowed on the same filter, and tags are normalized to lowercase.

You can use tags to:

• send different results to different Slack channels
• send different results to different email addresses
• create separate RSS feeds for different groups of filters
• distinguish results in the API

Example: Reddit agency

// client a
filter1 $tag:clienta
filter2 $tag:clienta

// client b
filter3 $tag:clientb
filter4 $tag:clientb

Example: Route by teams

You can create a separate Slack channel and send all posts made by teammates there, so that the rest of the team can quickly see them and upvote when appropriate.

// our company
ourcompany.com $tag:brand

// competitors
competitor1.com $tag:competitor
competitor2.com $tag:competitor

// upvotes
author:myself author:teammate1 author:teammate2 $tag:upvotes

Syften exposes a small JSON API for account settings, filters, and recent matches. Webhooks use the same match data structure and send new matches to your own endpoint as they arrive.

API token

You can copy or regenerate your API token in Setup → API and Zapier. Pass it in the Authorization header as a bearer token. There are sample curl scripts in the syften-examples repository.

curl https://syften.com/api/0.0/items/get \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20}'

Endpoints

All API endpoints use POST. Requests with a body should use Content-Type: application/json. Successful responses return the requested JSON data directly.

curl https://syften.com/api/0.0/filters/set \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filters": ["syften", "example.com NOT site:example.com"]}'

Items returned by items/get include the matched filter, the match timestamp, and the original item fields:

{
  "id": "match-id",
  "matched_on": "2026-05-04T12:34:56Z",
  "filter": "example.com",
  "item": {
    "backend": "reddit",
    "backend_sub": "r/startups",
    "type": "comment",
    "icon_url": "https://example.com/icon.png",
    "timestamp": "2026-05-04T12:34:56Z",
    "item_url": "https://example.com/thread",
    "author": "someuser",
    "text": "The matched text",
    "title": "Thread title",
    "title_type": 1,
    "lang": "en",
    "analysis": {
      "lang": "en",
      "sentiment": "neutral",
      "nsfw": false,
      "accept": true,
      "suggested_reply": "A short suggested reply, if available.",
      "score": 8,
      "excerpt": "The part of the item that matched the filter.",
      "rejection_reason": ""
    }
  }
}

Errors

Error responses use a JSON object with code and error. Common errors include a missing bearer token, an invalid token, an expired trial or subscription, an invalid endpoint, and malformed JSON.

{
  "code": 400,
  "error": "Authorization must be a Bearer type."
}

Webhooks

Webhooks are available on the Syften Pro plan. Configure your webhook URL in Setup → API and Zapier. There is a small webhook receiver example in the syften-examples repository.

When new matches are found, Syften sends a POST request to your URL with Content-Type: application/json. The request body is a JSON array of item objects, using the inner item shape from items/get. Each webhook item includes the matching filter in its filter field.

[
  {
    "backend": "reddit",
    "backend_sub": "r/startups",
    "type": "comment",
    "icon_url": "https://example.com/icon.png",
    "timestamp": "2026-05-04T12:34:56Z",
    "item_url": "https://example.com/thread",
    "author": "someuser",
    "text": "The matched text",
    "title": "Thread title",
    "title_type": 1,
    "filter": "example.com",
    "lang": "en",
    "analysis": {
      "lang": "en",
      "sentiment": "neutral",
      "nsfw": false,
      "accept": true,
      "suggested_reply": "A short suggested reply, if available.",
      "score": 8,
      "excerpt": "The part of the item that matched the filter.",
      "rejection_reason": ""
    }
  }
]

Return any 2xx status code to mark the webhook delivery as successful. Network errors and non-2xx responses are treated as failures.

Failed webhook deliveries are retried for up to 48 hours. Retries start with a minimum backoff of 5 minutes and can back off up to 12 hours between attempts. If the webhook URL is no longer valid, delivery is skipped instead of retried.

The API and webhook payload formats are intended for automation, but they are not version-locked. If you need a strict compatibility guarantee, contact us before relying on a field never changing.

Syften stores all of its processed items in an archive so you can search older items and test filters against them. The archive is meant to make filter development and iteration easier, especially when you want to sanity-check how a query behaves before relying on live results.

Not every source is included there. In particular, YouTube and Twitter/X results are not stored in the archive.

Technological limitations

The archive can search and retrieve information from very large datasets quickly because it relies on a data structure called an index. An index reorganizes the data to make queries fast, but that speed comes with a tradeoff: it does not preserve every detail of the original text, including punctuation such as dots, commas, and dashes. That is why search engines like Google often ignore punctuation as well.

When we return live results, we can afford to apply more computationally intensive processing. At that stage, we are able to take punctuation and other special characters into account much more precisely.

For example, Syften applies special handling for domains to ensure you get the results you actually mean. The filter example.com , when matching live results, would match:

• example.com
• www.example.com

But not:

• some-example.com
• example: com

The archive cannot see dots and similar punctuation precisely in the same way. So an archive search for website.so can still surface text like I built a website, so I launched it., even though that would not be treated as a real domain match in live results.