API reference - ProPR backend

The endpoints below automate administrative tasks the frontend also offers. Use the frontend for interactive configuration and these endpoints for scripting.

Every example targets the evaluation stack’s origin, https://localhost:5443. Its certificate is self-signed, so the examples pass curl -k. Behind your own ingress, substitute your API base URL.

PR finding metadata

GET /api/code-quality/findings returns collected finding metadata to callers with client access and the Code Insights capability. Scope the read with clientId, repositoryId, and pullRequestId. from and to are inclusive dates; omit them for the default thirty-day window.

limit is clamped to 1–200. offset skips matching rows and treats negative values as zero. Rows are ordered by review observation time descending and finding ID ascending. Read successive pages until a page contains fewer than limit rows. Each row includes the provider thread ID, legacy severity classification, nullable riskAssessment, classified core tags, disposition and nullable rejectionReason. An absent rejection reason represents an unknown or inapplicable reason.

riskAssessment contains impact, likelihood, confidence, derived severity, impactReason, likelihoodReason, confidenceReason, source and rubricVersion. HTTP enum values use lower camel case; Unknown serializes as unknown and Not applicable as notApplicable. Missing assessments remain null. The finding risk rubric defines severity and incomplete evidence. Confidence uses low, medium, high and certain; unknown is the unassessed state. Confidence requires a bounded rationale and does not change the severity matrix or numeric classifier confidence. Review status, completed results and protocol finding DTOs carry the same optional assessment.

Code Quality reads accept independent impact, likelihood, confidence and riskSeverity query selections. Omit a selection to include all values; use Unknown for unassessed evidence. Names are case-insensitive and unrecognized selections select Unknown. These filters also apply to findings drill-through and the legacy reviewer-performance metric reads. GET /api/code-quality/risk-over-time returns bucketed counts with dimension=impact, likelihood, confidence or riskSeverity (default), using the existing type-series response shape. It accepts the same date, client, repository, PR, file and risk scope and bucket=day|week|month.

Admin authentication

Exchange admin credentials for a JWT:

curl -k -X POST https://localhost:5443/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "<strong-password-here>"}'

The response body carries accessToken, expiresIn (seconds) and tokenType. The refresh token is issued as an httpOnly cookie, not in the body. Send Authorization: Bearer <accessToken> on subsequent requests. POST /api/auth/refresh reads that cookie and returns a new access token. It accepts a refreshToken field in the request body as a fallback for callers that cannot hold cookies.

An installation that turns off the password sign-in answers POST /api/auth/login with 409 for every account; see installation sign-in policy. Scripts on such an installation authenticate with a personal access token.

GET /api/auth/me returns the caller’s global role, per-client and per-tenant roles, the installation edition, and the state of every licensed capability.

Personal access tokens

For scripts and CI, use a personal access token, not an admin password. Create one under Settings → Personal Access Tokens in the frontend, or:

curl -k -X POST https://localhost:5443/api/users/me/pats \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"label": "ci-pipeline", "expiresAt": "2027-01-01T00:00:00Z"}'

label is required; expiresAt is optional and must be in the future when supplied. An expired date returns 400 without creating a token. The plaintext token is returned once and cannot be retrieved again. Send it in place of the bearer header:

curl -k https://localhost:5443/api/clients \
  -H "X-User-Pat: <token>"

List tokens with GET /api/users/me/pats and revoke one with DELETE /api/users/me/pats/<pat-id>. What a PAT can do, and how it is stored, is in automation credentials. Administrators can sign in through SSO and create a token under Settings → Personal Access Tokens.

GET /api/users/me/pats/policy returns maximumLifetimeDays for the authenticated user. A null value means no installation lifetime limit applies. Token creation and listing return the effective expiresAt, including the limit for provisioned users. If a request omits the expiry or selects a later date, ProPR uses the limit.

Tenant machine credentials

A platform administrator creates a credential with POST /api/admin/tenants/{tenantId}/machine-credentials, supplying label and optional future expiresAt. The token is returned once. GET lists metadata; DELETE /api/admin/tenants/{tenantId}/machine-credentials/{credentialId} revokes a credential.

External services send X-Tenant-Machine-Token and keep the token server-side.

Provisioned users

A hosting platform keeps the accounts of its customers with these endpoints. They require a platform administrator and the identity provider for provisioned users, which single sign-on for provisioned users configures. Without the provider, ProPR answers them with 404 and provisioned_sign_in_not_configured. {subject} is the subject of the person at that provider, as the sub claim of the ID token carries it, encoded as a path segment. Every operation is idempotent. Who signs in, and when the access of a user ends, is described under provisioned users.

ProPR answers a request for a subject whose account holds platform administrator rights with 409 and platform_administrator, and changes nothing. To delete a provisioned user, delete its account with DELETE /api/admin/users/{userId}/permanent. The platform can provision the subject again afterwards.

curl -k -X PUT "https://localhost:5443/api/admin/provisioned-users/7f1c2b9e-3a4d-4e5f-8a6b-9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -H "X-User-Pat: <token>" \
  -d '{"email": "ada@customer.example", "displayName": "Ada Customer"}'

curl -k -X PUT "https://localhost:5443/api/admin/tenants/<tenant-id>/provisioned-members/7f1c2b9e-3a4d-4e5f-8a6b-9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -H "X-User-Pat: <token>" \
  -d '{"clientIds": ["<client-id>"]}'

The person signs in through the button on /login, which opens GET /api/auth/provisioned-user/challenge with the page to return to in returnUrl.

Installation sign-in policy

These endpoints answer differently while the installation turns off the password sign-in (MEISTER_LOCAL_SIGN_IN_ENABLED=false) or the identity providers of tenants (MEISTER_TENANT_SSO_ENABLED=false); see installation sign-in policy.

Platform administrator elevations

A platform administrator starts an elevation for themselves to read the content of one tenant, or of one client of a tenant, for a limited time. The endpoints that need one are listed under platform administrator access to tenant content. All elevation endpoints require a platform administrator and the multi-tenancy capability.

curl -k -X POST https://localhost:5443/api/admin/elevations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{"tenantId": "<tenant-id>", "clientId": "<client-id>", "reason": "SUP-1042", "durationMinutes": 60}'

A content request of a platform administrator without an elevation answers 403:

{ "error": "...", "code": "elevation_required", "tenantId": "<tenant-id>", "clientId": "<client-id>" }

Tenant audit history

GET /api/admin/tenants/{tenantId}/audit-entries with optional page and pageSize returns the audit history of a tenant, the newest entry first, to its tenant administrators and to platform administrators. Each entry has an eventType, a summary, an optional detail, the acting user and the time. An entry that belongs to an elevation carries its elevationId; the event types of elevations are elevation.started, elevation.ended, elevation.expired and elevation.content_read. The endpoint requires the multi-tenancy capability.

Tenant review limits

A platform administrator limits how the reviews of a tenant run. GET /api/admin/tenants/{tenantId}/review-limits returns the two limits, and PUT on the same path stores them. Both answer 200 with the stored values:

{ "maxConcurrentReviews": 2, "maxReviewDurationSeconds": 1800 }

PUT stores both fields, so a field that is null or left out clears that limit. Sending the stored values again changes nothing. ProPR answers 400 with the field in errors when a value is outside its range, 404 for an unknown tenant, 401 without credentials and 403 when the caller is not a platform administrator. A change is recorded in the audit history of the tenant as tenant.review_limits.updated. Members of the tenant read the limits as reviewExecutionLimits in GET /api/admin/tenants/{tenantId}. How the limits act on reviews is described under tenant review limits.

curl -k -X PUT "https://localhost:5443/api/admin/tenants/<tenant-id>/review-limits" \
  -H "Content-Type: application/json" \
  -H "X-User-Pat: <token>" \
  -d '{"maxConcurrentReviews": 2, "maxReviewDurationSeconds": 1800}'

Repository review targets

All paths below start with /api/clients/{clientId}/review-targets. The client requires the crawl configuration capability. Each repository has its own target identity, including repositories in the same project or namespace.

Azure DevOps uses the saved organization URL as scopePath and requires providerScopePath on the selected connection’s origin. Enabled organization metadata must belong to that exact connection; a shared dev.azure.com origin does not establish coverage. Other providers use an owner or namespace and derive target scope from the connection host. Discovery returns the full namespace for nested repositories. Azure providerProjectKey is the stable project ID; providerProjectDisplayName is its browser-visible name. Provider-family values are azureDevOps, github, gitLab and forgejo.

Pull request discovery

All paths below start with /api/clients/{clientId}/review-targets. Every read, including cached reads, requires current client access, target policy and an active, verified selected connection covering the enabled saved scope. Adapters use that connection’s current credentials without another connection or installation-credential fallback. Tenant machine callers require current tenant ownership.

Installed adapters require positive native pull request or merge request numbers. The domain also stores an external review identifier; these operations do not accept opaque-only review identities.

The example ingress URL is POST https://localhost:5443/api/clients/{clientId}/review-targets/overview. Backend-relative OpenAPI paths omit the ingress /api prefix.

GitHub counts conversation comments, review comments and nonblank published review summaries; GitLab uses discussion notes; Azure DevOps uses live text comments and native thread status. Forgejo counts issue comments, published code comments and nonblank published review summaries once. Selected Forgejo verification and metadata preserve deployment prefixes; open-review discovery does not support them.

Client review history

All paths below start with /api/clients/{clientId}/reviewing. Reads remain available after SCM connections or targets are removed. Missing or foreign jobs return 404.

Completed-review usage export

GET /api/clients/{clientId}/reviewing/completed-usage requires X-Tenant-Machine-Token and current tenant ownership of the client.

Facts also contain sequence, jobId, clientId and completedAt. The response contains no machine token, provider secret or customer credit rate.

Client management

All paths below start with /api/clients.

Creating a client requires tenant administration; creating one in the System tenant requires platform administration. GET /api/admin/tenants lists available tenants. The seeded System tenant ID is 11111111-1111-1111-1111-111111111111.

SCM provider connections

All paths below start with /api/clients/{clientId}/provider-connections. Provider and authentication fields depend on the support matrix. Secrets are write-only.

GET /api/clients/{clientId}/provider-families returns the activation of every provider family of the installation, with providerFamily and isEnabled, to a caller with client access and to a tenant machine caller that owns the client. ProPR refuses a new connection of a disabled provider family with 409, so a service that creates connections for a client offers only the enabled families.

AI connection profiles

All paths below start with /api/clients/{clientId}/ai-connections. AI credentials describes provider-specific configuration.

Optional creationRequestId is a non-empty UUID for interrupted-creation readback. Create and list responses retain this immutable client-scoped identifier. Concurrent or later duplicate creation returns 409 without updating the existing profile or replaying 201. Retrieve the profile list to recover an uncertain result. The identifier is not a credential or TTL-based idempotency ledger; physical profile deletion permits later reuse. Omitted correlation remains null.

Every profile carries configurationRevision, which starts at 1. ProPR advances it when an update changes the provider, base URL, authentication mode, credential, default headers, default query parameters or provider settings. A rename, a model change and a credential the provider family renews on its own keep the revision.

Purpose bindings

Logical-model selection takes precedence over profile bindings.

Client model selection saves verified purpose bindings atomically and preserves them across restarts. Explicit logical-purpose mappings take precedence. A conflicting selection returns 409 and preserves the saved bindings. See client model selection.

Per-model inputs

Logical models and purposes

A logical-model name selects one model on one connection. A purpose selects a logical-model name.

The System tenant rejects tenant-catalog writes; its clients use overrides. Model catalog and pricing overrides use /api/tenants/{tenantId}/model-catalog/; see models and the catalog.

Scripted setup

Create the profile, verify it, activate it, then define logical models and assign purposes. Unmapped purposes cannot perform their workload.

Guided discovery endpoints

Guided configuration uses /admin/clients/{clientId}/connections/{connectionId}/discovery. Every request requires an explicit purpose: crawl, webhook, mention or procursor. Crawl discovery requires ClientUser and the crawl-configs capability. Mention discovery requires ClientAdmin, the mention-answering capability and native mention capabilities. Webhook and ProCursor discovery require ClientUser. These read permissions do not grant configuration writes.

Read descriptor for the native scope label, optional project stage, source kinds and supported operations. Read scopes, then projects when the descriptor declares a project stage. sources returns native repository identifiers, canonical references and persistent coordinates. selection resolves persistent coordinates even when a repository listing is empty. Use filters for crawl and webhook repository choices, and branches when supported.

curl -k "https://localhost:5443/api/admin/clients/<client-id>/connections/<connection-id>/discovery/descriptor?purpose=webhook" \
  -H "Authorization: Bearer <accessToken>"

curl -k "https://localhost:5443/api/admin/clients/<client-id>/connections/<connection-id>/discovery/scopes?purpose=webhook" \
  -H "Authorization: Bearer <accessToken>"

curl -k "https://localhost:5443/api/admin/clients/<client-id>/connections/<connection-id>/discovery/sources?purpose=webhook&scopeKey=<scope-key>&projectId=<project-id>&sourceKind=repository" \
  -H "Authorization: Bearer <accessToken>"

Unknown or missing purposes return HTTP 400. Empty lists return HTTP 200. Unsupported native operations return HTTP 501. Unavailable resources return HTTP 404; invalid connection selections or native discovery failures return HTTP 400 with sanitized guidance. Entitlement refusals return HTTP 409. A supplied connection must belong to the client and be active before native discovery runs.

Guided creates include connectionId and scopeKey. The server validates supplied provider and scope coordinates against the native selection. Manual configuration APIs require an explicit provider. Saved legacy configurations remain readable, and unrelated patches do not replace filters. Source discovery rejects scopes unavailable through the selected connection before repository queries. Saved native project names and ID casing resolve through native project metadata; patches retain stored coordinates. Repository-filter replacement preserves unchanged legacy targets with null canonical references. Retained mention repositories preserve omitted source metadata and claim times; explicit conflicting source coordinates are refused. Native project IDs take precedence over name fallback. Guided mention patches refuse changed canonical/provider coordinates for retained repository IDs even when they match live discovery.

ProCursor source management

Create a guided ProCursor source:

curl -k -X POST https://localhost:5443/api/admin/clients/<client-id>/procursor/sources \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Platform Docs",
    "sourceKind": "repository",
    "connectionId": "<connection-id>",
    "scopeKey": "<scope-key>",
    "organizationScopeId": "<scope-id>",
    "providerProjectKey": "my-project",
    "canonicalSourceRef": {
      "provider": "azureDevOps",
      "value": "repo-1"
    },
    "sourceDisplayName": "platform-docs",
    "defaultBranch": "main",
    "rootPath": "/docs",
    "symbolMode": "auto",
    "trackedBranches": [
      {
        "branchName": "main",
        "refreshTriggerMode": "branchUpdate",
        "miniIndexEnabled": true
      }
    ]
  }'

sourceKind must be declared by the selected connection descriptor. Knowledge-source creation requires its knowledge-source capability. Azure DevOps supports repository and adoWiki; other native adapters do not register knowledge-source materializers. refreshTriggerMode is manual or branchUpdate.

Crawl configurations

Crawl configurations require the crawl-configs capability; see editions. Resolve repository filters, then create one:

curl -k "https://localhost:5443/api/admin/clients/<client-id>/connections/<connection-id>/discovery/filters?purpose=crawl&scopeKey=<scope-key>&projectId=my-project" \
  -H "Authorization: Bearer <accessToken>"

curl -k -X POST https://localhost:5443/api/admin/crawl-configurations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{
    "clientId": "<client-id>",
    "connectionId": "<connection-id>",
    "scopeKey": "<scope-key>",
    "organizationScopeId": "<scope-id>",
    "providerProjectKey": "my-project",
    "crawlIntervalSeconds": 60,
    "reviewTemperature": 0.2,
    "repoFilters": [
      {
        "displayName": "platform-docs",
        "canonicalSourceRef": {
          "provider": "azureDevOps",
          "value": "repo-1"
        },
        "targetBranchPatterns": ["main"]
      }
    ],
    "proCursorSourceScopeMode": "selectedSources",
    "proCursorSourceIds": ["<source-id>"]
  }'

clientId is required. When selectedSources is used the chosen source IDs are snapshotted onto queued review jobs. reviewTemperature is optional; what it does and what it accepts is under what you can tune.

Webhook configurations

Webhook configurations are managed per client and can coexist with crawl configurations for the same repositories. Webhooks explains what one is, what to do with the secret it returns, and how to read its deliveries.

# List webhook configurations visible to the caller
curl -k https://localhost:5443/api/admin/webhook-configurations \
  -H "Authorization: Bearer <accessToken>"

# Create a webhook configuration
curl -k -X POST https://localhost:5443/api/admin/webhook-configurations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{
    "clientId": "<client-id>",
    "provider": "azureDevOps",
    "organizationScopeId": "<scope-id>",
    "providerProjectKey": "my-project",
    "reviewTemperature": 0.15,
    "enabledEvents": [
      "pullRequestCreated",
      "pullRequestUpdated",
      "pullRequestCommented"
    ],
    "repoFilters": [
      {
        "repositoryName": "platform-docs",
        "displayName": "platform-docs",
        "canonicalSourceRef": {
          "provider": "azureDevOps",
          "value": "repo-1"
        },
        "targetBranchPatterns": ["main", "release/*"]
      }
    ]
  }'

clientId is required, provider is one of azureDevOps, github, gitLab or forgejo, and enabledEvents accepts only the three names above. reviewTemperature is optional here too.

The create response carries:

• listenerUrl: the public HTTPS path your provider posts to
• generatedSecret: returned once at creation time
• repoFilters: the stored repository and branch scope, enforced on every delivery regardless of what the payload claims

Inspect recent delivery history for one webhook configuration:

curl -k "https://localhost:5443/api/admin/webhook-configurations/<config-id>/deliveries?take=20" \
  -H "Authorization: Bearer <accessToken>"

Each delivery-history entry records the sanitized incoming event summary, final outcome, response status, and the downstream actions that were invoked. What each outcome and status means, and what to change, is in webhook troubleshooting.

Update or delete an existing webhook configuration:

curl -k -X PATCH https://localhost:5443/api/admin/webhook-configurations/<config-id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{
    "isActive": false,
    "reviewTemperature": 0.0,
    "enabledEvents": ["pullRequestUpdated"],
    "repoFilters": []
  }'

curl -k -X DELETE https://localhost:5443/api/admin/webhook-configurations/<config-id> \
  -H "Authorization: Bearer <accessToken>"

Public webhook receiver

Point Azure DevOps webhooks at the one-time listenerUrl returned when the webhook configuration is created, and use Basic auth with the generated secret as the password.

curl -k -X POST https://localhost:5443/webhooks/v1/providers/ado/<path-key> \
  -H "Authorization: Basic <base64(username:generated-secret)>" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "git.pullrequest.updated",
    "resource": {
      "pullRequestId": 42,
      "repository": { "id": "repo-1" },
      "sourceRefName": "refs/heads/feature/webhooks",
      "targetRefName": "refs/heads/main",
      "status": "active"
    }
  }'

The receiver acknowledges every delivery that passes validation, including events it ignores:

{ "status": "accepted" }

{ "status": "ignored" }

The trigger decides when a review starts, not what it produces - see how a review gets triggered.

Trigger a review

Submit a pull request for review. Requires the ClientAdministrator role for the client.

curl -k -X POST https://localhost:5443/api/clients/<client-id>/reviewing/jobs \
  -H "Content-Type: application/json" \
  -H "X-User-Pat: <token>" \
  -d '{
    "provider": "azureDevOps",
    "hostBaseUrl": "https://dev.azure.com",
    "repository": {
      "externalRepositoryId": "repo-1",
      "ownerOrNamespace": "my-org",
      "projectPath": "my-project"
    },
    "codeReview": {
      "platform": "pullRequest",
      "externalReviewId": "42",
      "number": 42
    },
    "reviewRevision": {
      "headSha": "<head-sha>",
      "baseSha": "<base-sha>",
      "providerRevisionId": "3"
    }
  }'

provider, hostBaseUrl, repository and codeReview are required; number must be at least 1 and platform is pullRequest or mergeRequest. reviewRevision is optional, but if you send it, headSha and baseSha are required within it.

Send reviewRevision. ProPR treats a submission as a duplicate of an in-flight job only when the whole revision matches. Omit it and every submission for the same pull request collapses onto one revision, so a second push cannot be reviewed while the first review is still running.

A successful submission returns 202 Accepted with jobId and status. A 409 Conflict means an active job already exists for that revision, or the pull request is blocked. A review running on another pull request, or on this one at an earlier revision, is not a conflict. The submission is queued and starts once the installation’s concurrency ceiling allows it - see editions.

Trigger a review from coordinates alone

Submit configured repository coordinates to have ProPR read the current revision from the SCM host.

curl -k -X POST https://localhost:5443/api/clients/<client-id>/reviewing/jobs/by-coordinates \
  -H "Content-Type: application/json" \
  -H "X-User-Pat: <token>" \
  -d '{
    "providerScopePath": "https://dev.azure.com/my-org",
    "providerProjectKey": "my-project",
    "repositoryId": "<repository-id>",
    "pullRequestId": 42
  }'

The same request serves the first review and every re-review after new commits, because the revision is read fresh each time. An earlier job at an older revision is retired as superseded. Unlike the automatic triggers, this request reviews a revision that has already been reviewed, or that a previous review failed at. A review already running at this exact revision is not started twice.

Duplicate jobs and superseded jobs belong to the submitting client. Other clients reviewing the same pull request retain their jobs and results. Resumption and incremental result reuse also select only the submitting client’s history.

ClientUser is enough here, as it is for restart. Every response to a complete request carries a named outcome:

A request missing one of the four fields carries no outcome. It is refused with 400 and a plain {"error": "..."}, the shape the other endpoints on this page use.

Coverage or admission failures return submissionFailed without internal diagnostics. ProPR reads the revision fresh and rechecks current authorization, lifecycle and branch policy before queueing with the current source scope and temperature. Provider revision failures return revisionUnresolvable. Caller cancellation propagates before acceptance.

Blocking and dismissing

Block a pull request so no further review jobs are created for it. This does not stop a job that is already running - stop that job separately.

curl -k -X POST https://localhost:5443/api/clients/<client-id>/reviewing/blocked-prs \
  -H "Content-Type: application/json" \
  -H "X-User-Pat: <token>" \
  -d '{
    "providerScopePath": "https://dev.azure.com",
    "providerProjectKey": "my-project",
    "repositoryId": "repo-1",
    "pullRequestId": 42,
    "reason": "Generated code, not worth reviewing"
  }'

GET the same path to list current blocks, and POST the same body without reason to .../blocked-prs/unblock to lift one. Listing needs ClientUser; blocking and unblocking need ClientAdministrator.

Dismiss a finding so later reviews suppress similar ones:

curl -k -X POST https://localhost:5443/api/clients/<client-id>/reviewing/dismiss-finding \
  -H "Content-Type: application/json" \
  -H "X-User-Pat: <token>" \
  -d '{
    "findingMessage": "Prefer a guard clause here",
    "filePath": "src/Program.cs",
    "label": "style-preference"
  }'

findingMessage is required; filePath and label are optional. The call returns 201 with the stored memory record and requires ClientAdministrator.

Review diagnostics

GET /api/jobs/{id}/protocol returns one review’s protocol passes and events. Each event carries an eventCategory you can filter on. Pass includeEvents=false for an overview that keeps the event rows and metadata but omits their bodies, which is much cheaper on large reviews.

GET /api/jobs/{id} returns the detail of one review job. Its completionReason is timeLimitReached for a completed review that ended at the maximum review duration of its tenant, and none otherwise - see tenant review limits.

Diagnostics are scoped to a single review; there is no cross-review trace query.

Reading a protocol to answer a specific symptom starts at troubleshooting.

Reviewer performance

These Code Insights endpoints require tenant administration, the licensed capability and access to the selected clients. POST /api/reviewer-performance/ranges/query reads retained joint counts for one or two views under a consistent database snapshot:

{
  "bucket": "day",
  "aggregation": "cumulative",
  "grouping": "none",
  "views": [
    {
      "from": "2026-09-01",
      "to": "2026-09-30",
      "clientIds": null,
      "repositories": null,
      "models": null,
      "types": null,
      "qualifiers": null,
      "impacts": null,
      "likelihoods": null,
      "riskSeverities": null,
      "confidences": null
    }
  ],
  "breakdown": { "rows": "type", "columns": "qualifier", "date": "2026-09-30", "viewIndex": 0 }
}

bucket accepts day, week or month; aggregation accepts cumulative or period. Grouping accepts none, client, repository, model, type, qualifier, impact, likelihood, confidence or riskSeverity. Matrix axes use two distinct dimensions from that list, excluding none. Matrix date selects a bucket in its zero-based viewIndex; the response displays the clipped measurement window.

Null selections include all authorized values; empty arrays include none. Use returned facet IDs for repository and model selections because they include retained identity scope. The query permits 1–366 days per view, years 1900–9998, at most 128 selections per dimension, 100,000 retained joint cells per view, 24 series, 2,000 timeline points and 12 values per matrix axis. Source identity remains attached to cells. Each view permits 100,000 distinct retained source coordinates for optional link resolution, 100,000 exclusion catalog entries and 1,000,000 exclusion references across timeline and matrix points. Exceeded limits return 400 without truncating counts or exclusions. Unauthorized selected clients return 403.

Assessment selections use returned facet IDs, such as Critical, Certain, Unknown and NotApplicable. These IDs use the retained enum names; they differ from the lower-camel-case enum values in nested riskAssessment. Null or absent assessment selections include every value; empty arrays select no observations. Assessment dimensions use the same union-within-dimension and intersection-across-dimensions semantics as the other selections. view.evidence.riskRubricVersions captures versions observed in the retained source population. Risk restrictions, grouping and matrix axes make recall/F1 unavailable with miss-risk-assessment-unavailable until independently assessed human concerns are available. Supported overall precision remains available. Legacy risk-filtered whole-PR correctness returns sealed-risk-filter-unavailable instead of reusing an unfiltered score.

Each response includes calculation version, capture time, database evidence revision, authorized display facets, counts, all premise tuples, summaries, measurement windows and evidence limits. Projection timestamps describe source freshness separately from capture time. Cumulative measurements retain earlier evidence through the selected window; per-period measurements require activity in their own bucket. Scenario falseNegatives is null when its compatible FN population is unavailable. Model-specific recall/F1 requires complete compatible model opportunities and independent original human-concern evidence. Selected models use union detection and canonical misses, without summing singleton misses or PR coverage. Reviewer performance defines these scores and their evidence requirements.

Calculation version reviewer-performance-v2 captures the following populations and diagnostics:

Catalog IDs are zero-based and local to a view. A point’s exclusionIds selects its exact membership; the catalog can contain entries used only by other dates or intersections. Recovery dispositions are repair-required, retryable, collection-disabled, queued, in-progress, complete, ready, cooldown or unreconstructable-history. Optional recoveryAction is recollect-source, retry-model-evidence or none; an absent field retains the saved legacy collection interpretation. sourceConnectionId, lastModelRetryAt and modelRetryNotBefore capture the exact model source and local classification retry policy. No command runs when opening a saved report. For queued, notBefore records when the request becomes eligible for a sweep. For in-progress, it records the observation lease expiry. lastAttemptAt records the observation start, and lastCompletedAt records the latest successful completion. A retry timestamp does not schedule automatic work for a repair-required source. Optional source URLs use validated captured coordinates without provider requests. Successful open-thread judgments remain informational. Exclusion reasons and advisory minimums do not suppress supported recall/F1. At least one covered source is required; missing compatible model attribution still prevents those metrics. Empty denominators remain unavailable. Saved v1 and v2 responses preserve their captured values and availability policy.

POST /api/reviewer-performance/evidence/{aggregateId}/retry has no body and queues an authorized retained aggregate for a subsequent background sweep. It clears the old attempt token without changing evidence, scores or retention timestamps. It requires tenant administration and the licensed capability.

POST /api/reviewer-performance/evidence/{aggregateId}/retry-model takes {"providerScope":"<captured namespace>","connectionId":"<captured connection guid>"}. It retries bounded retained classification for that authorized source only, under the discussion lease and captured cooldown. It performs no provider reads or review execution and preserves original source cutoffs. 200 means the bounded attempt completed; refresh to inspect its result. 404 protects missing or foreign aggregates. 409 describes disabled collection, an active observation, cooldown, or unreconstructable retained proof; 503 indicates unavailable analytics services. Authentication and capability requirements match collection requeue. Wrong or ambiguous source identities cannot reset or replay another source’s concerns.

Model proof loading permits 4,096 jobs, 100,000 checkpoints and concern/decision rows, and 32 MiB each for execution proof and concern metadata. Before evaluating any series or matrix, model queries permit at most 8,192 concern/model evaluations, 1,000,000 candidate references and 1,000,000 pass references. An oversized evaluation returns 400 consistently across grouping and matrix traversal.

POST /api/reviewer-performance/reports takes {"id":"<guid>","name":"<name>","query":{...}} and captures the complete server response. Reuse the same ID and identical body for an idempotent retry; a different request with that ID returns 409. Report names permit 1–160 characters, and capture requires at least one authorized client. GET /api/reviewer-performance/reports lists up to 100 unexpired reports. GET /api/reviewer-performance/reports/{id} opens the stored response without live recalculation; DELETE on that path removes the complete report. Every report operation requires access to all contained clients, including idempotent capture retries. Missing, expired or unauthorized reports return 404. Capture refuses payloads above 32 MiB without truncation. Stored v1 reports keep their original scores; absent overall-precision or coverage fields are not reconstructed. Stored v2 reports retain their captured coverage policy and exclusion catalog even after source repair or configuration changes.

The misses browse response includes judgementFailed. When true, its three judgement flags are unavailable decisions, and the thread does not supply an eligible FN verdict. excludedAsOwnFinding identifies a current match to a retained reviewer finding. Its original human judgements remain present, but countsAsMiss is false.

Usage statistics

These operations require platform administration. Usage statistics describes the daily snapshot fields. Paths start with /api/admin/usage-statistics.

Health endpoints behind the proxy

Through the bundled reverse proxy, the API is reached under /api/ - that prefix is stripped before the request arrives, so the API’s own /healthz is /api/healthz from outside:

curl -k https://localhost:5443/api/healthz

https://localhost:5443/healthz without the prefix is answered by the frontend container’s own static health string and reports nothing about the API. What each check reports, and which endpoint to point a probe at, is in observability.

The same prefix rule applies to /metrics, which becomes /api/metrics - a path to block at your edge.

More

For every other endpoint - prompt overrides, dismissal search, token reporting, ProCursor token usage, tenant administration - read the OpenAPI specification.

In Development the API serves it at its own address: Swagger UI at /swagger, the document at /swagger/v1/swagger.json. Behind a reverse proxy that strips a leading /api, as the bundled one does, those become /api/swagger and /api/swagger/v1/swagger.json. Other environments serve neither, and the bundled stack runs in Production, so a stock deployment has no Swagger UI and no served document at any path. https://localhost:5443/swagger without the prefix is answered by the frontend container.

Script against openapi.json at the repository root instead. It is committed, and it covers every endpoint on this page except /healthz, /livez and /metrics, which observability describes. Its paths carry no /api prefix: /clients/{clientId}/ai-connections, not /api/clients/{clientId}/ai-connections. Through the bundled proxy, prepend https://localhost:5443/api as every example above does. The public webhook receiver is forwarded at its own path.