Quick Start: Client-Led Loop
Prefer to drive the LLM call yourself (a custom agent, the bundled example agent script, or any MCP client)? Use the ingest → loop → report workflow instead.
The steps below use curl. An MCP client runs the same loop through the MCP service. Either way, the API key determines which organization the changeset belongs to.
The examples read the key from OPENTREMOR_API_KEY. Create it with the pipeline role, the
default: it runs this loop and nothing else. In the dashboard, open Organization → Access → Service Accounts; or call
POST /v1/auth/keys with {"name": "ci", "role": "pipeline"}.
1. Ingest a diff
Section titled “1. Ingest a diff”Every pack starts off, so an admin must enable python-code-change first: Rules → Packs in the dashboard. Until then, this call returns 404.
curl -X POST -H "X-API-Key: $OPENTREMOR_API_KEY" \ "http://localhost:8000/v1/python-code-change/my-changeset/ingest" \ -H "Content-Type: text/plain" \ --data-binary @change.diffThe answer is a receipt. Keep revision_id:
{ "changeset": "my-changeset", "revision_id": "9f3c...", "unit_count": 12, "pending_count": 12, "units": [ {"unit_hash": "9c2a7e1f...", "type": "async_function", "name": "export_invoices", "action": "add", "pack": "python-code-change"} ]}rule_type and repository are optional. The revision stores them, and every claim returns the
matching rules.
2. Claim units and submit their analysis
Section titled “2. Claim units and submit their analysis”# Claim a batch: 5 units by default, 20 at mostcurl -X POST -H "X-API-Key: $OPENTREMOR_API_KEY" http://localhost:8000/v1/my-changeset/claims \ -H "Content-Type: application/json" \ -d '{"limit": 5, "revision_id": "9f3c...", "known_rulesets": []}'{ "status": "units", "revision_id": "9f3c...", "progress": {"total": 12, "analysed": 0, "claimed": 5, "claimable": 7}, "contract_id": "c_8a41...", "contract": "## Your answer ...", "rulesets": {"r_5d1e...": {"rule_ids": ["PYCC-001", "..."], "text": "# Python code-change review rules ..."}}, "units": [ {"unit_hash": "9c2a7e1f...", "ruleset_id": "r_5d1e...", "type": "async_function", "name": "export_invoices", "action": "add", "body": "[email protected](\"/export\")\n+async def export_invoices(org_id: str, ...) ...", "metadata": {"pack": "python-code-change", "source_path": "billing/api/invoices.py"}} ]}Analyse each unit’s body against rulesets[unit.ruleset_id], write the analysis as contract
says, then submit the batch:
curl -X POST -H "X-API-Key: $OPENTREMOR_API_KEY" http://localhost:8000/v1/my-changeset/analyses \ -H "Content-Type: application/json" \ -d '{ "revision_id": "9f3c...", "analyses": [{ "unit_hash": "9c2a7e1f...", "verdict": "The export takes the tenant from the query string, not from the signed-in user.", "findings": [{ "rule_id": "PYCC-001", "title": "Invoice export scoped by an org_id from the query string", "severity": "CRITICAL", "confidence": "HIGH", "consequence": "Any signed-in member can pass the ID of another organization and download its invoices.", "rationale": "A cross-tenant leak of payment data breaks the isolation customers rely on.", "remediation": "Drop the org_id parameter and filter on principal.org_id.", "quotes": ["+ rows = await invoices.find({\"org_id\": org_id}).to_list(None)"], "tags": ["tenant-isolation"] }] }] }'The answer lists each unit’s status: stored, or rejected with the errors to fix before
you send that unit again. Then claim again. List the ruleset_ids you already hold in
known_rulesets, and the contract_id in known_contract, so their text is not sent again.
status tells you what to do next:
status | Do |
|---|---|
units | Analyse and submit the units, then claim again |
waiting | Another caller holds the remaining units. Claim again after retry_after_seconds |
done | Every unit is analysed. Go to step 3 |
If you stop before done, release your claims so the units are immediately claimable:
curl -X DELETE -H "X-API-Key: $OPENTREMOR_API_KEY" "http://localhost:8000/v1/my-changeset/claims?revision=9f3c..."3. Get the report
Section titled “3. Get the report”# Markdowncurl -H "X-API-Key: $OPENTREMOR_API_KEY" "http://localhost:8000/v1/changesets/my-changeset/report?revision=9f3c..."
# HTMLcurl -H "X-API-Key: $OPENTREMOR_API_KEY" "http://localhost:8000/v1/changesets/my-changeset/report?revision=9f3c...&format=html" > report.htmlSee LLM Agent Workflow for the full loop, error handling, and multi-pack changesets.
Next steps
Section titled “Next steps”See Triage a Finding to suppress a finding, or Authentication to set up a real multi-tenant deployment. Prefer a single call with no loop to drive? See Server-Side Analysis.