> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set or clear paths filters on jobs

> Requires the **Update Dynamic CI settings** permission.

Sets a paths filter on each job named in `filters`, and removes it from each job in `clear`. Name a job by its workflow file and its key under `jobs:`. Each filter applies to pull requests and the merge queue alike. A request names at most 500 jobs in all, across every `filters[].jobs` and `clear`.

It changes only the jobs it names. It never deletes a filter; one the request leaves with no jobs stays in the list, with no jobs. Sending the same body again changes nothing, so no `Idempotency-Key` is needed. A job that already has a different filter fails the request with `PATHS_FILTER_CONFLICT` unless `overwrite` is true. Any error means nothing was written.



## OpenAPI

````yaml /openapi-v2beta-dynamic-ci.json patch /v2beta/dynamic-ci/paths-filters
openapi: 3.1.0
info:
  title: Trunk Dynamic CI API (beta)
  version: 0.1.0
  description: >-
    Dynamic CI endpoints in beta. They may change without notice, and are
    promoted to `/v2` when they are stable. Authentication, errors and rate
    limits are those of the Trunk API v2.
  contact:
    name: Trunk Support
    url: https://docs.trunk.io
servers:
  - url: https://api.trunk.io
    description: Production
security:
  - apiKey: []
  - trunkToken: []
tags:
  - name: dynamicCi
    x-group: Dynamic CI
paths:
  /v2beta/dynamic-ci/paths-filters:
    patch:
      tags:
        - dynamicCi
      summary: Set or clear paths filters on jobs
      description: >-
        Requires the **Update Dynamic CI settings** permission.


        Sets a paths filter on each job named in `filters`, and removes it from
        each job in `clear`. Name a job by its workflow file and its key under
        `jobs:`. Each filter applies to pull requests and the merge queue alike.
        A request names at most 500 jobs in all, across every `filters[].jobs`
        and `clear`.


        It changes only the jobs it names. It never deletes a filter; one the
        request leaves with no jobs stays in the list, with no jobs. Sending the
        same body again changes nothing, so no `Idempotency-Key` is needed. A
        job that already has a different filter fails the request with
        `PATHS_FILTER_CONFLICT` unless `overwrite` is true. Any error means
        nothing was written.
      operationId: dynamicCi.setPathsFilters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPathsFiltersRequest'
      responses:
        '200':
          description: What the request did to each job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetPathsFiltersResult'
        '400':
          description: '`VALIDATION_FAILED` | `CI_HOST_UNSUPPORTED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                VALIDATION_FAILED:
                  summary: VALIDATION_FAILED
                  value:
                    error:
                      code: VALIDATION_FAILED
                      message: 'Invalid input: expected string, received undefined'
                CI_HOST_UNSUPPORTED:
                  summary: CI_HOST_UNSUPPORTED
                  value:
                    error:
                      code: CI_HOST_UNSUPPORTED
                      message: >-
                        Dynamic CI does not support the repository host
                        gitlab.example.com
        '401':
          description: >-
            `AUTHENTICATION_REQUIRED` | `INVALID_TOKEN`. A malformed, expired,
            or deleted credential. Trunk's edge usually answers this before the
            request reaches the API, with a body that is not this envelope
            (`{"error": "unauthorized: invalid api key"}` for a bad API key, or
            plain text for a bad `x-trunk-token`), so branch on the status. A
            request with no credential at all gets `403` from the edge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AUTHENTICATION_REQUIRED:
                  summary: AUTHENTICATION_REQUIRED
                  value:
                    error:
                      code: AUTHENTICATION_REQUIRED
                      message: No credential was supplied
                INVALID_TOKEN:
                  summary: INVALID_TOKEN
                  value:
                    error:
                      code: INVALID_TOKEN
                      message: The supplied token failed verification
        '403':
          description: '`INSUFFICIENT_PERMISSIONS`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INSUFFICIENT_PERMISSIONS:
                  summary: INSUFFICIENT_PERMISSIONS
                  value:
                    error:
                      code: INSUFFICIENT_PERMISSIONS
                      message: >-
                        The supplied credential is missing the required
                        permission
        '404':
          description: '`REPOSITORY_NOT_FOUND` | `CI_SCOPE_NOT_FOUND`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                REPOSITORY_NOT_FOUND:
                  summary: REPOSITORY_NOT_FOUND
                  value:
                    error:
                      code: REPOSITORY_NOT_FOUND
                      message: Repository not found
                CI_SCOPE_NOT_FOUND:
                  summary: CI_SCOPE_NOT_FOUND
                  value:
                    error:
                      code: CI_SCOPE_NOT_FOUND
                      message: >-
                        A workflow or job in the request does not belong to this
                        repository
        '409':
          description: '`PATHS_FILTER_CONFLICT`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PATHS_FILTER_CONFLICT:
                  summary: PATHS_FILTER_CONFLICT
                  value:
                    error:
                      code: PATHS_FILTER_CONFLICT
                      message: >-
                        1 job already has a different paths filter:
                        .github/workflows/ci.yml test (job
                        3c4f8e21-6a1d-4b7e-9f02-5d8c1a2b3e4f, "backend"). Send
                        "overwrite": true to replace them.
        '429':
          description: >-
            `RATE_LIMIT_EXCEEDED`. Trunk's edge answers this, and does not yet
            wrap it in the error envelope or send `Retry-After`: treat any `429`
            as rate limiting, whatever its body, and retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RATE_LIMIT_EXCEEDED:
                  summary: RATE_LIMIT_EXCEEDED
                  value:
                    error:
                      code: RATE_LIMIT_EXCEEDED
                      message: Rate limit exceeded; retry with backoff
        '500':
          description: '`INTERNAL_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INTERNAL_ERROR:
                  summary: INTERNAL_ERROR
                  value:
                    error:
                      code: INTERNAL_ERROR
                      message: An unexpected error occurred
components:
  schemas:
    SetPathsFiltersRequest:
      type: object
      properties:
        repo:
          $ref: '#/components/schemas/PlanRepo'
        overwrite:
          type: boolean
          default: false
          description: >-
            Replace a different filter already on a job. Without it, such a job
            fails the request with `PATHS_FILTER_CONFLICT`.
          example: false
        filters:
          type: array
          items:
            $ref: '#/components/schemas/PathsFilterEntry'
          maxItems: 100
        clear:
          type: array
          items:
            $ref: '#/components/schemas/JobRef'
          maxItems: 500
          description: Jobs to remove the paths filter from.
      required:
        - repo
      additionalProperties: false
    SetPathsFiltersResult:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/WrittenFilter'
          maxItems: 100
          description: >-
            One per `filters` entry, leaving out an entry none of whose jobs
            resolved.
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/WrittenJob'
          maxItems: 500
          description: >-
            One per job named, in request order. A job named by `jobId` is
            reported by its path and key.
      required:
        - filters
        - jobs
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: >-
                Human-readable description of what went wrong. Not stable — do
                not parse.
              example: An unexpected error occurred
          required:
            - code
            - message
      required:
        - error
      description: >-
        The error envelope. Every error this API itself returns has this shape,
        except a `413` for a body over 512 KB and a `504` for a request that
        runs past its time limit, which are plain text. Responses from Trunk's
        edge, such as a `401`, a `403` for a missing credential, a `429` or a
        `503`, can arrive before the request reaches the API and may not have
        it, so read `error.code` only when the body is JSON with an `error`
        object.
    PlanRepo:
      type: object
      properties:
        host:
          type: string
          default: github.com
          description: >-
            Disambiguates GitHub.com from a GitHub Enterprise Server host.
            `github.com` is the only supported value today.
          example: github.com
        owner:
          type: string
          example: acme
        name:
          type: string
          example: widgets
      required:
        - owner
        - name
    PathsFilterEntry:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          maxLength: 80
          description: >-
            Trimmed; blank or absent is unnamed. Names a new filter, or an
            existing unnamed one with the same rules; an existing name is kept.
          example: web
        rules:
          $ref: '#/components/schemas/PathsFilterRulesInput'
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobRef'
          minItems: 1
          maxItems: 500
      required:
        - rules
        - jobs
      additionalProperties: false
    JobRef:
      anyOf:
        - $ref: '#/components/schemas/JobRefByName'
        - $ref: '#/components/schemas/JobRefById'
      description: A job, as `{ workflowPath, jobKey }` or as `{ jobId }`.
    WrittenFilter:
      type: object
      properties:
        pathsFilterId:
          type: string
          example: e8f1c2a4-5b6d-4e7f-8a9b-0c1d2e3f4a5b
        name:
          type:
            - string
            - 'null'
          description: The stored name, which an existing named filter keeps.
          example: web
        status:
          $ref: '#/components/schemas/WrittenFilterStatus'
        jobCount:
          type: integer
          description: Distinct jobs on the filter after the write.
          example: 1
      required:
        - pathsFilterId
        - name
        - status
        - jobCount
    WrittenJob:
      type: object
      properties:
        workflowPath:
          type:
            - string
            - 'null'
          example: .github/workflows/ci.yaml
        jobKey:
          type:
            - string
            - 'null'
          example: web-unit
        status:
          $ref: '#/components/schemas/WrittenJobStatus'
        jobIds:
          type: array
          items:
            type: string
          maxItems: 500
          description: >-
            Every job the name matched; one name can match more than one. Empty
            for `unresolved`.
          example:
            - 3c4d0b17-8e2a-4f6c-9d1b-7a5e3c2f1d0e
      required:
        - workflowPath
        - jobKey
        - status
        - jobIds
    ErrorCode:
      type: string
      enum:
        - AUTHENTICATION_REQUIRED
        - INVALID_TOKEN
        - INSUFFICIENT_PERMISSIONS
        - INTERNAL_ERROR
        - VALIDATION_FAILED
        - NOT_FOUND
        - INVALID_CURSOR
        - MERGE_QUEUE_NOT_FOUND
        - PR_ALREADY_ENQUEUED
        - PR_NOT_ENQUEUEABLE
        - UPSTREAM_ERROR
        - VERIFICATION_RUN_NOT_FOUND
        - PR_NOT_FOUND
        - IMPACTED_TARGETS_NOT_FOUND
        - REPOSITORY_NOT_FOUND
        - IMPACTED_TARGETS_UNSUPPORTED
        - QUEUE_ALREADY_EXISTS
        - QUEUE_HAS_ACTIVE_ENTRIES
        - MODE_CHANGE_IN_PROGRESS
        - PR_NOT_IN_ACTIVE_STATE
        - MERGE_QUEUE_NOT_CREATABLE
        - PR_TESTS_NOT_RESTARTABLE
        - ALLOWED_BOT_SUBMITTERS_FROZEN
        - ESTIMATE_NOT_ENABLED
        - PR_RERUN_FEATURE_DISABLED
        - PR_RERUN_NOT_PENDING_FAILURE
        - PR_RERUN_QUEUE_DOES_NOT_KEEP_FAILED_RUNS
        - PR_RERUN_NOT_A_REQUIRED_CHECK_FAILURE
        - PR_RERUN_CHECK_NOT_RERUNNABLE
        - PR_RERUN_RUN_TORN_DOWN
        - PR_RERUN_HOLD_LIMIT_REACHED
        - PR_RERUN_FORGE_NOT_SUPPORTED
        - PROVIDER_URL_NOT_FOUND
        - CI_HOST_UNSUPPORTED
        - CI_SCOPE_NOT_FOUND
        - PATHS_FILTER_CONFLICT
        - CI_JOB_NOT_FOUND
        - CI_FAILURE_CLUSTER_NOT_FOUND
        - TEST_COLLECTION_NOT_FOUND
        - TEST_NOT_FOUND
        - TEST_UPLOAD_NOT_FOUND
        - MONITOR_NOT_FOUND
        - MONITOR_LIMIT_EXCEEDED
        - MONITOR_NOT_ACTIVE
        - OUT_OF_RANGE
        - TEST_UNAVAILABLE
        - TICKETING_NOT_CONFIGURED
        - TICKETING_CREDENTIALS_INVALID
        - TICKETING_SITE_REFUSED
        - TICKET_NOT_FOUND
        - TICKET_NOT_LINKED
        - TICKET_LINK_CONFLICT
        - TEST_ALREADY_LINKED
        - TICKET_FIELDS_REJECTED
        - TICKET_CONTENT_UNAVAILABLE
        - TICKETING_CREATE_REFUSED
        - RATE_LIMIT_EXCEEDED
      description: >-
        Stable machine-readable error identifier. Switch on this, never on
        `message`. A shipped code's meaning never changes, but **new codes may
        be added within v2** — treat an unrecognized code as a generic failure
        of its HTTP status rather than failing closed.
      example: INTERNAL_ERROR
    PathsFilterRulesInput:
      type: object
      properties:
        include:
          type: array
          items:
            $ref: '#/components/schemas/PathsFilterRule'
          minItems: 1
          maxItems: 64
          example:
            - glob: web/**
        exclude:
          type: array
          items:
            $ref: '#/components/schemas/PathsFilterRule'
          maxItems: 64
          description: Defaults to none.
          example:
            - glob: web/**/*.md
      required:
        - include
      additionalProperties: false
    JobRefByName:
      type: object
      properties:
        workflowPath:
          type: string
          minLength: 1
          description: The workflow file's repository-relative path, exactly.
          example: .github/workflows/ci.yaml
        jobKey:
          type: string
          minLength: 1
          description: The job's key under `jobs:` in that file.
          example: web-unit
      required:
        - workflowPath
        - jobKey
      additionalProperties: false
    JobRefById:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
          description: >-
            A job's id from `dynamicCi.listPathsFilters` or
            `dynamicCi.listPrJobs`. A `workflowPath` or `jobKey` sent beside it
            must name the same job.
          example: 3c4f8e21-6a1d-4b7e-9f02-5d8c1a2b3e4f
        workflowPath:
          type:
            - string
            - 'null'
          minLength: 1
          description: The workflow file's repository-relative path, exactly.
          example: .github/workflows/ci.yaml
        jobKey:
          type:
            - string
            - 'null'
          minLength: 1
          description: The job's key under `jobs:` in that file.
          example: web-unit
      required:
        - jobId
      additionalProperties: false
    WrittenFilterStatus:
      type: string
      enum:
        - new
        - existing
      description: Whether the request created the filter or found it by its rules.
      example: new
    WrittenJobStatus:
      type: string
      enum:
        - set
        - unchanged
        - cleared
        - unresolved
      description: >-
        `set`: the job now has the filter. `unchanged`: nothing was written.
        `cleared`: its filter was removed. `unresolved`: Trunk has not seen the
        job run, so nothing was written; send the request again after it runs.
      example: set
    PathsFilterRule:
      type: object
      properties:
        glob:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            A picomatch glob, matched with `dot: true` against the
            repository-relative path. May not begin with `!` or `(`.
          example: web/**
        changeTypes:
          type: array
          items:
            $ref: '#/components/schemas/ChangeType'
          minItems: 1
          maxItems: 6
          description: Match only these kinds of change. Absent matches any.
          example:
            - added
            - modified
      required:
        - glob
      additionalProperties: false
    ChangeType:
      type: string
      enum:
        - added
        - copied
        - deleted
        - modified
        - renamed
        - unmerged
      description: A kind of file change, as `dorny/paths-filter` names them.
      example: modified
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key, sent as `Authorization: Bearer <key>`. An organization admin
        creates one in the Trunk app under **Settings → Developer → API Keys**
        and chooses the permissions it holds. A key with none can read merge
        queues but change nothing in them. Permissions cover merge queues and
        test-result uploads, including the quarantine lookups a CI run makes
        before it uploads; any key can call the other Flaky Tests and Dynamic CI
        endpoints, including their writes.
    trunkToken:
      type: apiKey
      in: header
      name: x-trunk-token
      description: >-
        A short-lived token that Trunk's own tools send in the `x-trunk-token`
        header: the `trunk` CLI after `trunk auth login`, and the
        `trunk-io/login` action in a GitHub Actions run. Your own integrations
        should use an API key instead. Never send `Authorization` and
        `x-trunk-token` on the same request.


        **A token from a GitHub Actions run can only upload and read impacted
        targets** (`PUT /v2/impacted-targets` and `GET
        /v2/pull-requests/{id}/impacted-targets`), for the repository the run
        belongs to. On a pull request from a fork it can also call the Flaky
        Tests CLI endpoints. Every other endpoint refuses it.

````