Skip to content
DashboardWebsite

Server-Side Analysis

The LLM Agent Workflow has the client drive the ingest, analysis and submission steps, calling the LLM between steps. POST /v1/{pack}/{changeset}/analyze moves that workflow to the server: send raw input and name an LLM connection and model. The server ingests the input, analyzes each unit, and returns a report or a job to poll. The GitHub App integration uses this endpoint.

Use this endpoint when you do not need to control the LLM calls yourself, such as from a script or a client that does not call tools.


POST /v1/{pack}/{changeset}/analyze
body: {connection_id, model, api_key?, raw_input, rule_type?, categories?, repository?}
input at or below server.sync_analysis_max_units
-> 200 {job_id, revision_id, report_markdown, resource_count, quota_exceeded}
-> recorded as a mode:"sync" job; GET /v1/jobs/{job_id} returns its status
input above the threshold
-> 202 {job_id, status: "queued", revision_id}
-> poll GET /v1/jobs/{job_id} until status is "done" or "failed"
-> after "done", GET /v1/changesets/{changeset}/report returns the report

The unit count is based on the input the pack ingests. The default threshold is 5 units. You can change it with server.sync_analysis_max_units.

This endpoint shares ingestion and rule selection with the client-led workflow. Both workflows skip units that already have an analysis in the changeset.


Every request names an LLM target in connection_id. You can pass an inline API key or use a stored LLM connection.

  1. Inline key: Set connection_id to a hosted provider kind such as anthropic, openai or mistral, and pass api_key in the request body. The key is not stored.
  2. Stored connection: Create an LLM connection, then send its connection_id. The server uses the connection’s stored credential.

In the dashboard: Organization → Connections → LLM. Or create a connection through the API:

Terminal window
# Store a connection once (org-admin)
curl -X POST http://localhost:8000/v1/orgs/default/llm-connections \
-H "X-API-Key: <admin-key>" -H "Content-Type: application/json" \
-d '{"connection_id": "anthropic", "provider_kind": "anthropic", "api_key": "sk-ant-..."}'

Stored keys are encrypted at rest with Fernet and are never returned by the API after saving.


Terminal window
jq -n \
--arg raw_input "$(git diff origin/main -- '*.py')" \
'{connection_id: "anthropic", model: "claude-sonnet-5", raw_input: $raw_input}' \
| curl -s -X POST http://localhost:8000/v1/python-code-change/billing-pr-42/analyze \
-H "X-API-Key: <your-key>" -H "Content-Type: application/json" -d @-
FieldRequiredDescription
connection_idYesA stored connection, or a hosted provider kind (anthropic, mistral, openai) with an inline api_key
modelYesProvider-specific model name, such as claude-sonnet-5
api_keyNoInline key; when omitted, the server uses the stored key if the connection has one
raw_inputYesRaw input accepted by the pack, like the text sent to .../ingest
rule_typeNoRule variant for a pack that has several, such as django for python-code-change
categoriesNoRule category IDs to check, such as ["performance"]. Omit to run every rule. See Rule Categories in a Run
repositoryNoRepository in provider/external_id form; selects repository-scoped rules and settings

When the input produces at or below server.sync_analysis_max_units units (default 5), the request waits for analysis to finish and returns the report:

{
"job_id": "b7e2c1a4-...",
"revision_id": "revision-id",
"report_markdown": "# 🤖 Analysis Report\n...",
"resource_count": 3,
"quota_exceeded": false
}

The server records the run as a mode: "sync" job. You can look up its status with GET /v1/jobs/{job_id}. If an LLM response error causes a 502, the response includes job_id, and the job records the error so you can retry it with POST /v1/jobs/{job_id}/retry. An inline job cannot be cancelled.

When the input produces more units than the threshold, the request returns a job to poll:

{"job_id": "b7e2c1a4-...", "status": "queued", "revision_id": "revision-id"}

Poll the job until its status is done or failed:

Terminal window
curl -s http://localhost:8000/v1/jobs/b7e2c1a4-... -H "X-API-Key: <your-key>"

A completed job includes fields such as:

{
"job_id": "b7e2c1a4-...",
"status": "done",
"mode": "async",
"trigger": "api",
"resource_count": 14,
"quota_exceeded": false,
"error": null
}

After it reaches done, fetch the report:

Terminal window
curl "http://localhost:8000/v1/changesets/prod-deploy-42/report"

If the organization has a monthly LLM spending limit (Organization → Usage & Audit → Quota in the dashboard, or PATCH /v1/orgs/{org_id}/quota), the server applies it to LLM usage:

  • Budget already spent: The request returns 402 before analysis starts.
  • Budget reached during analysis: Analysis stops early. The response or job sets quota_exceeded: true; the report covers the units analyzed before the budget was reached.
Terminal window
curl -X PATCH http://localhost:8000/v1/orgs/default/quota \
-H "X-API-Key: <admin-key>" -H "Content-Type: application/json" \
-d '{"monthly_budget_usd": 50.0}'
curl http://localhost:8000/v1/orgs/default/usage -H "X-API-Key: <admin-key>"
# {"period": "2026-07", "total_cost_usd": 12.34, "budget_usd": 50.0, "remaining_usd": 37.66, "billed_quantity": 84, ...}

See Billing / quota endpoints.


StatusMeaning
200Analysis completed synchronously; response includes the report
202Job queued; poll GET /v1/jobs/{job_id}
400Missing credential, or the provider/model pair is not in the allowed-models catalog
402The org’s monthly LLM budget is already spent, or the org is not entitled to run analysis
404Unknown pack, pack not enabled for the org or repository, repository not listed, or a file needed during analysis is missing
413Input exceeds server.max_input_size_mb
422A selected category has no rule for this pack and repository
501Pack does not support ingestion
502The LLM response could not be parsed or stopped at analysis.llm_max_output_tokens. This applies to the sync path; async failures are recorded on the job. A sync error response includes job_id

Server-side /analyzeClient-led workflow
Calls needed1, plus an optional job pollOne per unit, plus ingest and report calls
Who calls the LLMThe serverYour client or agent
Prompt controlServer promptYour client controls the prompt
Best forScripts and internal toolingCustom agents, MCP clients and non-standard LLM providers

Both workflows use the same data model and can contribute analyses to one changeset. An MCP client can start server-side analysis with the start_server_analysis tool of the MCP service. The run uses the organization associated with the client’s credential. See Architecture — Server-side analysis.