Filters

By default a generation considers every connected source in a project. A SourceFilter narrows that down per source – useful when you only care about one repo, one branch, or one priority of issues.

Shape

filters is an object keyed by source. Each source accepts up to four arrays, AND-combined:

json

{
  "github": { "projects": ["acme/payments"], "branches": ["main"], "eventTypes": ["push"] },
  "linear": { "priorities": ["high"] }
}

Field	Meaning
`projects`	Resource ids – repos, channels, boards.
`branches`	Git branch names (git sources only).
`eventTypes`	Event types to keep (e.g. `push`, `issue`).
`priorities`	Priority labels (e.g. `high`, `urgent`).

A source omitted from filters is left unconstrained. Within a source, the arrays combine with AND: a GitHub event must match a listed repo and a listed branch and a listed event type to be included.

Discover valid values

Do not guess filter values – fetch the real selectable options for a project with the filters endpoint:

bash

curl "https://www.flowrelay.it/api/v1/handoffs/filters?project_id=proj_8c1d" \
  -H "Authorization: Bearer fr_your_api_key"

json

{
  "filters": {
    "github": {
      "projects": [{ "id": "acme/payments", "label": "acme/payments" }],
      "branches": [{ "value": "main", "label": "main" }],
      "eventTypes": [{ "value": "push", "label": "Push" }],
      "priorities": []
    }
  }
}

Use the id / value fields when building a SourceFilter.

Examples

Only the main branch of one repo:

json

{ "filters": { "github": { "projects": ["acme/payments"], "branches": ["main"] } } }

Only high-priority Jira issues:

json

{ "filters": { "jira": { "priorities": ["high"] } } }

Filters apply identically to handoffs (POST /handoffs) and insights (POST /projects/{id}/insights/{kind}). When you omit sources and filters entirely, the project's saved scope preferences are used.