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.
How the endpoint responds
Section titled “How the endpoint responds”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 reportThe 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.
1. Choose an LLM connection
Section titled “1. Choose an LLM connection”Every request names an LLM target in connection_id. You can pass an inline API key or use a stored LLM connection.
- Inline key: Set
connection_idto a hosted provider kind such asanthropic,openaiormistral, and passapi_keyin the request body. The key is not stored. - 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:
# 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.
2. Send the analysis request
Section titled “2. Send the analysis request”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 @-| Field | Required | Description |
|---|---|---|
connection_id | Yes | A stored connection, or a hosted provider kind (anthropic, mistral, openai) with an inline api_key |
model | Yes | Provider-specific model name, such as claude-sonnet-5 |
api_key | No | Inline key; when omitted, the server uses the stored key if the connection has one |
raw_input | Yes | Raw input accepted by the pack, like the text sent to .../ingest |
rule_type | No | Rule variant for a pack that has several, such as django for python-code-change |
categories | No | Rule category IDs to check, such as ["performance"]. Omit to run every rule. See Rule Categories in a Run |
repository | No | Repository in provider/external_id form; selects repository-scoped rules and settings |
3. Read the result
Section titled “3. Read the result”Small input: synchronous response
Section titled “Small input: synchronous response”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.
Larger input: asynchronous job
Section titled “Larger input: asynchronous job”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:
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:
curl "http://localhost:8000/v1/changesets/prod-deploy-42/report"Billing and quota
Section titled “Billing and quota”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
402before 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.
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.
Errors
Section titled “Errors”| Status | Meaning |
|---|---|
200 | Analysis completed synchronously; response includes the report |
202 | Job queued; poll GET /v1/jobs/{job_id} |
400 | Missing credential, or the provider/model pair is not in the allowed-models catalog |
402 | The org’s monthly LLM budget is already spent, or the org is not entitled to run analysis |
404 | Unknown pack, pack not enabled for the org or repository, repository not listed, or a file needed during analysis is missing |
413 | Input exceeds server.max_input_size_mb |
422 | A selected category has no rule for this pack and repository |
501 | Pack does not support ingestion |
502 | The 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 |
Choose server-side or client-led analysis
Section titled “Choose server-side or client-led analysis”Server-side /analyze | Client-led workflow | |
|---|---|---|
| Calls needed | 1, plus an optional job poll | One per unit, plus ingest and report calls |
| Who calls the LLM | The server | Your client or agent |
| Prompt control | Server prompt | Your client controls the prompt |
| Best for | Scripts and internal tooling | Custom 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.