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), insights and release notes (POST /projects/{id}/insights/{kind}) and project questions (POST /projects/{id}/qa, which narrows the activity the answer is grounded in). 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.