HTTP API

Who am I, what may I touch, and what is my record

Call this first. Returns your scopes (which services and paths you may change), your remaining budget for today, and your measured track record per service — the same numbers policy uses to decide whether your next change lands unattended.

Propose a change — the only way code reaches trunk

Submits a complete change object: your stated intent, the spec you worked to, the diff, the results you observed, and your session trace. Trunk verifies the diff itself, scores risk against your track record in this service, and applies repo policy. Configured required external checks are created and dispatched automatically for the exact immutable candidate revision; callers do not need to start Trunk-managed CI manually. If policy says auto_land and every required external check is green for the current revision, an ordinary Change lands. A Draft-controlled revision remains open until that exact revision is marked Ready. Human-routed changes still require a decision, and neither approval nor Ready bypasses required gates.

List changes

Get one change, with whichever parts you need

Re-run verification and re-route

Rebuilds the evidence bundle from scratch, re-scores risk against the current track record, and re-applies policy. Any approval bound to an older evidence digest is invalidated. After verification materializes the current immutable candidate, configured required external checks are dispatched automatically. Re-running verification safely reuses/reconciles the same durable first-attempt CI identity.

Record a human decision or terminate a pre-evidence Change

Human-only. request_key is the caller-stable idempotency boundary: retry the exact same request with the same key after any lost or ambiguous response; reusing a key with different input fails closed. With verification evidence present, a decision is bound to that evidence. Before verification evidence exists, only reject is accepted and no Decision row is recorded. The response distinguishes the durable Decision outcome from the follow-on landing outcome; approval does not bypass required external checks.

Land an approved or auto-landable change on trunk

Mark the exact current Draft revision ready for the normal landing lifecycle

Only the Change author may open landing readiness for the exact numerical Change revision supplied by the caller. It creates no evidence and bypasses no policy, approval, check, Preview, freshness, source or publication fence. A stale revision is rejected.

Revert a landed change

Reverts on trunk and attributes the outcome to the change's author. This is what moves an agent's track record, which is what changes how its next change routes.

Append steps to a change session trace

The human decision queue — only what policy could not resolve

Issue a short-lived human Git HTTPS credential

Issues a short-lived credential for the repository’s Trunk-owned HTTPS Git remote. Read credentials permit clone/fetch. Write credentials additionally return the authenticated actor’s allowed Human Work ref prefix; Trunk landing remains the only normal canonical publication path.

Start or resume an initial repository import

Requires repository-admin authority. Reserves one durable import operation using bounded commit/source/digest/size metadata, or reconciles the same operation after an interrupted raw-pack upload. Bulk Git-pack bytes are uploaded separately to the returned Trunk-owned binary transfer URL and never travel through JSON or MCP.

Inspect the durable repository import operation

Requires repository-admin authority. Returns bounded metadata and the durable import state. This operation never carries Git-pack bytes or performs provider mutation.

List repositories

Create a repository

Creates a repository, its services, and version 1 of its routing policy. Services are how Trunk assigns a change to an owner and a criticality, and they are what track records are measured against — a repository with no services still works, but every change lands as "unassigned" at medium criticality. Human-only: registering repositories is not an agent operation. The creating human becomes repository administrator and check administrator in the durable preparation transaction before provider provisioning begins. CI is disabled by default. A repository admin can enable Trunk-managed CI from Integrations.

Repository detail: services, ownership, active policy, trunk head

Read the active routing policy

Replace the routing policy (creates a new version)

Replay a candidate policy over historical changes

Answers the only question that matters before changing policy: how many of the last N changes would this have auto-landed, and which ones would it have stopped?

Read several files from one exact branch snapshot

Reads up to 12 repository files in one call. The named branch is resolved once and every file is read at that immutable head commit. Missing paths are reported separately. Aggregate returned text is capped at 2097152 bytes.

Search text source at one exact branch snapshot

Bounded literal text search over the provider-neutral repository browser. The named branch is resolved once and the complete traversal reads its immutable head commit. Binary files are ignored. Results may be marked truncated when the result cap, provider truncation, or hard scan bounds are reached.

Preflight a textual patch against the exact recorded Trunk head

Read-only exact applicability check for an existing unified Git text diff. Trunk captures its current recorded commit SHA once, reads affected paths at that immutable commit, and verifies supported add/modify/delete hunks without fuzzy relocation. The result is convenience evidence for a later trunk_propose_change call using the returned base_commit; it does not reserve, authorize, materialize, or mutate anything. Diff input is capped at 524288 bytes and source reads reuse the bounded multi-read limits. Rename/copy, binary, mode-only and no-trailing-newline forms fail closed.

The branches this repository holds

Trunk lands on one branch and creates no others, so this is whatever the underlying Git provider actually has. The trunk branch is flagged and listed first. Reads are only served for a branch that appears here.

One directory of the source at one branch

Directories first, then files, each alphabetically. Omit `path` for the repository root, and `ref` for the trunk branch. A `ref` naming no branch is a 404 rather than a silent fall back to trunk.

One file of the source at one branch

Text arrives as `text`; a blob that is not decodable text comes back with `text: null` and `binary: true`. Large files are truncated to whole lines with `truncated: true`, and `bytes` is always the size of the whole blob.

The trunk log: what landed, in order

The agent fleet with track records

One agent: scopes, budget, per-service record

Register an agent identity

Human-only. Returns the API key once; it is not retrievable afterwards.

Delete an agent that never did anything

Human-only. Removes the identity along with its scopes, budget and API keys. Refused with a 409 once the agent has a record — a proposed change, a revert, an attested check run. That history is signed by this actor and policy reads it, so it outlives any wish to tidy the fleet up; revoke the agent's keys instead, which stops it working and leaves what it did readable.

Grant an agent a scope

Set an agent budget

List an agent's active API keys

Names and previews only. A key itself is readable exactly once, when it is issued.

Issue a new API key

Returns the key once. Only its digest is stored, so it cannot be recovered afterwards — reissue instead. An agent may hold several keys at once, which is how you rotate without downtime: issue the new one, move the agent across, then revoke the old one.

Revoke an API key

The key stops authenticating immediately. The record of it is kept, so a key that was used and then taken away stays visible.

Recent platform events

Throughput and autonomy for the repo

Create an account

Creates a human identity and opens a session. Agents cannot call this: registering people is not an agent operation.

Exchange an email and password for a session token

End the current session

Dispatch or retry an exact required check in Trunk-managed CI

Manual/admin handoff for a configured Trunk-managed required check after Trunk has materialized and verified an immutable candidate. Normal first-attempt CI is orchestrated automatically; this surface remains human-attester-only for explicit recovery/bootstrap and terminal retry. The requested provider/check is revalidated as a required repository check under the same repository lock that creates the queued CheckRun and durable dispatch intent. The stable managed-CI provider identity is trunk-ci; the backing execution provider is intentionally not part of this public contract. The caller supplies the exact candidate SHA it observed; Trunk binds the request to the current numbered Change revision and uses the same rolling-safe first-attempt identity selection as automatic orchestration, so manual/automatic races converge while distinct numbered revisions can never collapse merely because they resolve to the same candidate SHA. To rerun a terminal non-success provider-owned check on the same revision, retryOf names the exact prior durable dispatch; Core derives exactly one child request identity from that parent, so replay is idempotent and concurrent retries cannot fan out.

Create or replay an exact-revision deployment and dispatch supported Preview providers

Server-only deployment handoff for an explicitly authorized deployer. Durable deployment intent is committed before provider handling. New Vercel Preview creates resolve the repository's durable Vercel installation/project connection, capture the exact immutable Trunk candidate source proof, and stay durably NOT_STARTED while read-only preflight positively proves that project already has a Production deployment. Only then may Trunk publish STARTED and transport the exact candidate directly to Vercel without a GitHub bridge or Production target. Existing STARTED attempts continue to reconcile against their pinned provider target, including the recovery-only legacy target format used before repository-scoped integrations, and require authoritative provider read-back. Historical unsupported SHA-256 Preview attempts that are still positively pre-mutation are retired to cancelled on replay rather than remaining queued forever; STARTED and terminal historical attempts retain their existing recovery/replay semantics. Terminal idempotent replays return durable state without requiring historical provider credentials. Production remains intent-only and therefore cannot invoke Vercel here.

Report provider-observed state for one deployment attempt

Server-only provider-neutral result handoff. Any currently authorized deployer for the repository may reconcile the attempt, which permits credential rotation and failover. The deployment domain still enforces monotonic state, immutable terminal outcomes, immutable provider identity/URL and idempotent replay.

Read the required external checks for a repository

Returns stable public check identities. Trunk-managed CI is identified as trunk-ci; customer-selected external providers retain their provider identity.

Replace the required external checks for a repository

Repository check-admin policy. Providers report check state; they never decide whether their own check is required for landing. Public signup alone grants no check-admin authority. Trunk-managed CI uses stable trunk-ci/<workflowName> identities; provider-specific managed execution remains internal. Policy storage commits before reconciliation. New managed requirements are activated for already-verified candidate revisions, while only already-approved changes may resume landing. If post-commit managed-CI activation is unavailable, the request reports a provider-neutral retryable error and the saved policy remains authoritative.

Read current revision-bound checks and the landing gate

Create a human-attested check run for the current change revision

Bootstrap surface for human-attested or non-integrated check providers. The Trunk-managed CI identity is reserved for its authenticated handoff/result path, so a human cannot manufacture a later managed attempt that supersedes provider-owned evidence. Genuine customer-selected or non-managed providers retain their own provider identity. Other checks require repository check-attester authority and reject stale revisions.

Advance a human-attested check run and resume landing when the gate turns green

Check state is monotonic. A completed conclusion is immutable; replaying the same update is idempotent and emits no duplicate event. Only the explicitly repository-authorized actor that created the attestation may update it, and CheckRuns bound to external-CI dispatches are provider-owned and rejected by this human surface.