> ## 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.

# Replace a pull request's force overrides

> Requires the **Force CI jobs to run** permission.

Sets the complete list of forces active on a pull request. **This replaces the set, it does not add to it** — a force you omit is revoked, and an empty list clears them all. Send the desired end state, not a delta.

Scopes are addressed by the `workflowId` and `jobId` that `dynamicCi.listPrJobs` returns. An already-active force is left alone, so re-sending an unchanged list changes nothing. Forces are applied the next time `dynamicCi.generatePlan` runs for this pull request; this does not re-run anything itself.



## OpenAPI

````yaml /openapi-v2beta-dynamic-ci.json put /v2beta/dynamic-ci/force-overrides
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/force-overrides:
    put:
      tags:
        - dynamicCi
      summary: Replace a pull request's force overrides
      description: >-
        Requires the **Force CI jobs to run** permission.


        Sets the complete list of forces active on a pull request. **This
        replaces the set, it does not add to it** — a force you omit is revoked,
        and an empty list clears them all. Send the desired end state, not a
        delta.


        Scopes are addressed by the `workflowId` and `jobId` that
        `dynamicCi.listPrJobs` returns. An already-active force is left alone,
        so re-sending an unchanged list changes nothing. Forces are applied the
        next time `dynamicCi.generatePlan` runs for this pull request; this does
        not re-run anything itself.
      operationId: dynamicCi.setForceOverrides
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetForceOverridesRequest'
      responses:
        '204':
          description: The forces were replaced
        '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
        '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:
    SetForceOverridesRequest:
      type: object
      properties:
        repo:
          $ref: '#/components/schemas/PlanRepo'
        prNumber:
          type: integer
          exclusiveMinimum: 0
          example: 4213
        headSha:
          type: string
          minLength: 1
          description: >-
            The pull request's head commit, recorded with each force as evidence
            of what it was saved against.
          example: 9f2c1b7c2b4c9d1e0a3f5b6c7d8e9f0a1b2c3d4e
        overrides:
          type: array
          items:
            $ref: '#/components/schemas/ForceOverrideRequest'
          maxItems: 1000
          description: >-
            The complete desired set. An empty array clears every force on the
            pull request.
      required:
        - repo
        - prNumber
        - headSha
        - overrides
    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
    ForceOverrideRequest:
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/ForceOverrideScope'
        workflowId:
          type: string
          format: uuid
          description: >-
            Required for `workflow` and `job`; rejected on a `pullRequest`
            scope, which would otherwise force the whole pull request without
            saying so.
          example: 2b3c4d5e-0000-4000-8000-000000000002
        jobId:
          type: string
          format: uuid
          description: >-
            Required for `job`; rejected on any other scope, which would
            otherwise force more than the job named.
          example: 3c4d5e6f-0000-4000-8000-000000000003
      required:
        - scope
    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
    ForceOverrideScope:
      type: string
      enum:
        - pullRequest
        - workflow
        - job
      description: >-
        What a force covers: every job on the pull request, every job in one
        workflow, or a single job.
      example: job
  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.

````