API reference

BNLGit 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

Your instance serves an interactive API browser at /api/swagger, but it documents Gitea's endpoints only — the BNLGit 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; "Pro" means the route is available only when the instance runs the Pro edition.

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, Pro	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.

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"
}

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

Pro. See Model bake-off.

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

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

Cleanup plans

Pro. See AI repo cleaner and steward.

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

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, Pro
`POST`	`/api/v1/bnlgit/mcp`	Token, `repository` scope, Pro

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. Two worth calling out:

404 from a Pro-gated route means the edition is not Pro, or the Pro licence is missing or expired — not that the repository is missing.
429 from bake-offs means you hit a per-user or per-repository hourly rate limit.

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