---
title: Programmatic API
description: Run a provider-neutral Bugbot review through the request-only package API.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.page/vypdev/copilot/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmatic API

Import the API from `@vypdev/copilot/bugbot`. Construct
`BugbotReviewService` with provider-neutral findings and SCM ports, then pass a
single `BugbotReviewRequest` to `review`.

```ts
import {
  ApplicationError,
  BugbotReviewService,
  type BugbotReviewRequest,
  type BugbotScmGateway,
  type FindingsQueryPort,
  type MessageCatalogResolutionPort,
} from '@vypdev/copilot/bugbot';

const service = new BugbotReviewService(findingsPort, scmGateway);

const request: BugbotReviewRequest = {
  target: {
    kind: 'pull-request',
    number: 42,
    head: 'feature/42-checkout',
    base: 'develop',
  },
  agent: {
    provider: 'codex',
    modelProvider: 'openai',
    model: 'gpt-6-luna',
    executable: 'codex',
  },
  configuration: { publicationMode: 'dry-run', effort: 'high' },
};

try {
  const results = await service.review(request);
  for (const result of results) {
    for (const error of result.errors) console.error(error.toJSON());
  }
} catch (error) {
  if (error instanceof ApplicationError) console.error(error.toJSON());
  else throw error;
}
```

`target` is a discriminated union: use `kind: 'pull-request'` with a positive
PR number and head branch, or `kind: 'branch'` with a branch name. Runtime input
is validated and bounded even when JavaScript bypasses TypeScript.

The returned error array is readonly and contains only semantic
`ApplicationError` values. `toJSON()` exposes the safe message, code, category,
retry decision, impact, action, retained state, and correlation ID. It never
includes a token, provider payload, raw cause, stack, prompt, command arguments,
or local path.

`locale.issue` and `locale.pullRequest` accept canonicalizable BCP-47 tags and
default independently to `en-US`. Branch or issue-only publication uses the
issue locale; publication attached to a verified pull request uses the pull
request locale. Invalid tags and unknown locale keys fail before analysis or
publication.

The optional third constructor argument is a `MessageCatalogResolutionPort`.
English and Spanish are bundled. For any other valid locale, the service asks
that resolver for one complete catalog per review, including every cardinal
plural category required by the locale, and reuses it across the
status card, review snapshot, inline findings, overflow, and resolution notes.
An absent resolver, failed request, or incomplete response falls back atomically
to English; a review never mixes partially translated catalog entries. Dry-run,
skipped, superseded, and issue-only no-mutation paths do not resolve a
presentation catalog.

The API intentionally has no overload accepting the internal runtime aggregate
and does not export `Execution` or `Ai`. It also never accepts a token in the
request. Callers expose the bound `{ owner, name }` repository identity on the
`BugbotScmGateway` and keep its credentials closed inside the adapter before
constructing the service; review workflows
receive only capability methods. Internal orchestration and authority remain
package-owned.

Construction validates, copies, and freezes the gateway's `{ owner, name }`
identity. Mutating the caller-owned gateway object later cannot redirect a
review or desynchronize its operation context from the already-bound SCM
methods. An incomplete identity fails immediately with a semantic validation
error.

See [Application error reference](/security-operations/operations/error-reference)
for the stable code meanings and operator actions.

### Native dismissal re-verification

Custom SCM adapters may add `listPullRequestReviewThreadStates` to the bound
publication and resolution ports (and the corresponding unbound port). It
returns current native thread facts keyed by the original review-comment
identity. The GitHub composition already supplies this query with its existing
repository identity and credential binding.

The query is optional for existing adapters, preserving their existing
operations. Re-adjudicating an explicitly reopened dismissal requires a fresh
fact for that exact comment. A missing query, missing entry, invalid fact or
failed read stops the mutation through the existing review-operation error;
it never grants authority to overwrite the dismissed reason. A thread that is
resolved again is preserved. Keep the original finding/review identity and use
the normal recheck after repairing adapter access. No approval policy setting
or permission expansion is needed.

### Source-bound large reviews

Bugbot passes the selected head SHA as the optional second argument to
`context.getReviewDiffSnapshot`. Gateways that read a mutable PR diff can use
that argument to verify the revision and report coverage from the full
changed-file inventory. Existing gateway implementations can continue to
accept only the PR number.

To support the large framed profile, a custom gateway additionally supplies
`reviewSource.readCompleteSource`
and `context.getSourceBoundPullRequest`. The latter returns the complete current
PR identity, including the separately queried live target branch `baseRefSha`,
base ref/comparison SHA, head repository/ref/SHA and native changed-file count.
A missing or failed identity read never establishes freshness.

The source port runs in the trusted host and returns complete immutable verified
source for the pinned identity, not a model assertion or a workspace placeholder.
It must prove full native/immutable path inventory, unique merge-base, regular
UTF-8 object contents and patch binding under the closed limits in
[How it works](/bugbot/how-it-works#complete-review-of-large-diffs).
Keep credentials inside bound adapters and do not execute consumer source.
The built-in GitHub composition supplies the canonical live-ref query and the
bounded local read-only Git adapter.

If either capability is absent, an over-envelope review returns
`validation.evidence-unavailable` / `bugbot-review-incomplete` with resource
`capability`, without reviewer calls or SCM publication. It never silently uses
an incomplete ordinary result. Framed dry-run follows all source, receipt and
freshness checks while preserving the no-write contract. No request field can
increase profile limits or bypass the independent approval policy.
