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.

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

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

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.

Every field of a generation request is validated before any work is enqueued, so a malformed request can never quietly narrow the scope of a generation you are billed for. Flow Relay is strict where it can be certain and lenient where the value is provider-driven:

Hard-rejected with 400 (the response names the field and lists what is allowed):

• An unknown source in sources or an unknown key in filters.
• An unknown filter dimension (only projects, eventTypes, branches, priorities exist).
• branches on a non-git source, or priorities on a source that has no priority concept.
• Any unknown top-level field – the body must contain only the documented parameters.
• Malformed shape: a non-array where an array is expected, an empty or over-long string, an out-of-range number.

{
  "error": "Invalid request: filters.slack.branches – Branch filtering is not supported for \"slack\". It applies to git sources only.",
  "issues": [
    {
      "field": "filters.slack.branches",
      "message": "Branch filtering is not supported for \"slack\". It applies to git sources only.",
      "allowed": ["github", "gitlab", "bitbucket", "azure_devops"]
    }
  ]
}

Matched leniently – the eventTypes, priorities and projects values come straight from the external platforms (a git host emits pr_<action> / mr_<action> directly), so an allow-list would be perpetually incomplete and would reject legitimate values. A value that does not exist simply matches no events; it is not rejected. Use GET /handoffs/filters to discover the values that actually apply to a project.

Because the request is validated up front and an over-restrictive filter short-circuits to a "no activity" outcome before the model runs, a rejected or empty-matching request never spends credits.

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

curl "https://www.flowrelay.it/api/v1/handoffs/filters?project_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer fr_your_api_key"

{
  "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. The filters endpoint only returns the sources actually connected to the project; the full closed vocabulary of every source is listed below.

Only the main branch of one repo:

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

Only high-priority Jira issues:

{ "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.

Selecting figma (in sources or filters) does more than filter events: the generation attaches visual context – rendered previews of your team's top frames plus an indexed scene graph (layout, text content, prototype flows and, on Figma Enterprise, design variables).

Two constraints apply:

• Global region only. Figma can be selected only on projects whose processing region is Global. On EU or self-hosted projects the API responds 400 and the dashboard shows Figma as non-selectable. Figma events still flow in as text when you don't filter for them explicitly.
• Visual surcharge. A generation that attaches frame renders costs 1 extra credit on top of the flow's flat price. Text-only Figma activity carries no surcharge.

The filters endpoint returns a figma availability block alongside the options:

{
  "filters": { "...": {} },
  "figma": {
    "selectable": true,
    "region": "default",
    "scope": "personal",
    "canManageResidency": true,
    "residencyHref": "/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6#data-residency"
  }
}

Check figma.selectable before offering Figma as a filter option in your own tooling.