API reference

ProofGit adds a small set of endpoints under Gitea's existing /api/v1 tree. Everything else in that tree is Gitea's own API, documented by Gitea ↗, and unchanged.

Why this page exists

The forge serves an interactive API browser at /api/swagger, but it documents Gitea's endpoints only — the ProofGit routes below carry no swagger annotations and therefore do not appear there. This page is the reference for them until that gap is closed.

Authentication

Standard Gitea personal access tokens. Mint one at Settings → Applications.

Authorization: token <your-token>

Authorization: Bearer <your-token> is also accepted.

The scope a route needs is listed in the tables below. "Repo writer (code)" means write access to the repository's code unit.

Instance

Method	Path	Auth	Notes
`GET`	`/api/v1/bnlgit/capabilities`	None	Edition, licence status, feature flags, drift thresholds. Deliberately unauthenticated so a script or agent never has to guess what is enabled.
`POST`	`/api/v1/bnlgit/mcp`	Token, `repository` scope	Fleet MCP server. See Connect your agent.

Repository pairing

Method	Path	Auth	Notes
`GET`	`/api/v1/repos/{owner}/{repo}/bnlgit/pair`	Repo reader	Current pair state for the repository.
`POST`	`/api/v1/repos/{owner}/{repo}/bnlgit/pair`	Repo writer (code)	Create the pairing. Requires `llm_credential_ref` and `llm_model`.
`POST`	`/api/v1/repos/{owner}/{repo}/bnlgit/repair`	Repo writer (code)	Repair a pairing whose mirror was damaged or deleted, without losing its history.
`PATCH`	`/api/v1/repos/{owner}/{repo}/bnlgit/skip-policy`	Repo writer (code)	Replace the pairing's file scope: `skip_presets`, `skip_deny` and `skip_allow` — see Repo scope. Changes those three settings and nothing else; returns the updated pairing.

POST /api/v1/repos/acme/order-service/bnlgit/pair
Authorization: token <your token>
Content-Type: application/json

{
  "llm_credential_ref": "openrouter-primary",
  "llm_model": "anthropic/claude-sonnet-5"
}

The skip policy has no partial update: send all three lists, with the complete policy you want, on every call. A missing list is a 400. An empty skip_presets list switches every preset off; it does not restore the defaults.

PATCH /api/v1/repos/acme/order-service/bnlgit/skip-policy
Authorization: token <your token>
Content-Type: application/json

{
  "skip_presets": ["secrets_material", "node_modules", "vendor", "build_output", "lockfiles"],
  "skip_deny": ["scripts/deploy-hook.php"],
  "skip_allow": []
}

Summary jobs

The unit of work behind the Sync Cockpit. One job corresponds to one file's summary.

Method	Path	Auth	Notes
`GET`	`.../bnlgit/summary-jobs`	Repo reader	List jobs and their states.
`POST`	`.../bnlgit/summary-jobs/sync`	Repo writer (code)	Reconcile the job list against the current tree.
`POST`	`.../bnlgit/summary-jobs/claim`	Repo writer (code)	Claim jobs for generation.
`GET`	`.../bnlgit/summary-jobs/{id}`	Repo reader	One job.
`POST`	`.../bnlgit/summary-jobs/{id}/regenerate`	Repo writer (code)	Request regeneration — this is what actually authorises spend.
`POST`	`.../bnlgit/summary-jobs/{id}/unflag`	Repo writer (code)	Dismiss a `needs_regeneration` flag, recording who and when.
`POST`	`.../bnlgit/summary-jobs/{id}/generated`	Repo writer (code)	Record a completed generation.
`POST`	`.../bnlgit/summary-jobs/{id}/failed`	Repo writer (code)	Record a failure, retaining the error.
`POST`	`.../bnlgit/summary-jobs/{id}/skipped`	Repo writer (code)	Record a deliberate skip.

Model bake-offs

See Model bake-off.

Method	Path	Auth
`GET`	`.../bnlgit/model-bakeoffs`	Repo reader
`POST`	`.../bnlgit/model-bakeoffs`	Repo writer (code)
`GET`	`.../bnlgit/model-bakeoffs/{id}`	Repo reader

POST requires "confirm_cost": true and honours an Idempotency-Key header.

Cleanup plans

See AI repo cleaner and steward.

Method	Path	Auth
`GET`	`.../bnlgit/cleanup-plans`	Repo reader
`POST`	`.../bnlgit/cleanup-plans`	Repo writer (code)
`GET`	`.../bnlgit/cleanup-plans/{id}`	Repo reader

POST requires "confirm_cost": true when it includes analysis types that make provider calls.

MCP

Method	Path	Auth
`POST`	`/api/v1/repos/{owner}/{repo}/bnlgit/mcp`	Token
`POST`	`/api/v1/bnlgit/mcp`	Token, `repository` scope

JSON-RPC 2.0. Full detail, including tool names and client configuration, is in Connect your agent (MCP).

Any endpoint that can spend from your BYOK connection rejects a request that does not carry cost consent:

{ "confirm_cost": true }

Without it you get a 400 explaining that the request would spend from your connection. This is enforced server-side and is not something a client can opt out of. See Managed worker and spend controls.

Errors

Standard Gitea API error shapes and status codes. One worth calling out:

429 from bake-offs means you hit a per-user or per-repository hourly rate limit.

Something here wrong or missing? Mail hello@proofgit.com — these pages are the single public source of truth for ProofGit and we would rather fix them than leave you guessing.