Skip to content
DashboardWebsite

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

Every pack starts off, so an admin must enable python-code-change first: Rules → Packs in the dashboard. Until then, this call returns 404.

Terminal window
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.diff

The 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.

Terminal window
# Claim a batch: 5 units by default, 20 at most
curl -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:

Terminal window
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:

statusDo
unitsAnalyse and submit the units, then claim again
waitingAnother caller holds the remaining units. Claim again after retry_after_seconds
doneEvery unit is analysed. Go to step 3

If you stop before done, release your claims so the units are immediately claimable:

Terminal window
curl -X DELETE -H "X-API-Key: $OPENTREMOR_API_KEY" "http://localhost:8000/v1/my-changeset/claims?revision=9f3c..."
Terminal window
# Markdown
curl -H "X-API-Key: $OPENTREMOR_API_KEY" "http://localhost:8000/v1/changesets/my-changeset/report?revision=9f3c..."
# HTML
curl -H "X-API-Key: $OPENTREMOR_API_KEY" "http://localhost:8000/v1/changesets/my-changeset/report?revision=9f3c...&format=html" > report.html

See LLM Agent Workflow for the full loop, error handling, and multi-pack changesets.


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.