The NeuroScan API
Analyze a Python project, read the findings, fix them with a metered AI run, download the patched tree. One bearer key, a job id, and a JSON answer per call — no browser, no clicking.
1. Create a key on your account (API keys → Create key). 2. Use it:
curl -s https://neuromomen.com/api/v1/me \
-H "Authorization: Bearer $ARCHSCAN_KEY"
Analysis costs nothing: the findings come from the AST, and the description pass is never billed.
The AI fix is metered per
model call — price it with dry_run before you run it.
The flow
# 1. upload (free) - a zip, or a public GitHub repo
curl -s -X POST https://neuromomen.com/api/v1/projects \
-H "Authorization: Bearer $ARCHSCAN_KEY" -F file=@project.zip
# -> {"ok":true,"job":"5f3c…","status":"analyzing"}
# 2. poll until done
curl -s https://neuromomen.com/api/v1/jobs/5f3c… -H "Authorization: Bearer $ARCHSCAN_KEY"
# -> {"ok":true,"status":"done","issues":[{"id":3,"code":"architecture/import-cycle",…}],"counts":{…}}
# 3. price the fix, then run it
curl -s -X POST https://neuromomen.com/api/v1/jobs/5f3c…/fix \
-H "Authorization: Bearer $ARCHSCAN_KEY" -H "Content-Type: application/json" \
-d '{"dry_run":true}' # {"calls":5,"seconds":100,"balance":400000}
curl -s -X POST https://neuromomen.com/api/v1/jobs/5f3c…/fix \
-H "Authorization: Bearer $ARCHSCAN_KEY" -H "Content-Type: application/json" -d '{}'
# 4. the patched project
curl -sL https://neuromomen.com/api/v1/jobs/5f3c…/download \
-H "Authorization: Bearer $ARCHSCAN_KEY" -o fixed.zip
Endpoints
| Call | What it does |
|---|---|
GET /api/v1 | service descriptor, no key needed |
GET /api/v1/openapi.json | OpenAPI 3.1 — generate a client from it |
GET /api/v1/me | balance, free projects, this run's limits |
POST /api/v1/projects | zip (multipart file) or {"repo":"owner/name"} |
GET /api/v1/jobs/{job} | status, findings; ?full=1 adds the graph |
POST /api/v1/jobs/{job}/fix | fix everything, or {"issues":[3,7]}; dry_run prices it |
GET /api/v1/jobs/{job}/download | the patched project (409 while a run is writing) |
GET /api/v1/jobs/{job}/report | the whole report as one offline HTML file |
Optional extras on upload: ?summaries=1 writes an AI sentence per function (free - no
tokens are charged), ?warm=1 pre-decides the patches so the fix starts instantly and is paid:
it spends the fix's tokens at upload time.
Failures say what to do
{"detail":"Out of tokens - top up from $5 on /account",
"error":{"code":"money/empty","message":"…","supportedFixes":["top up at /account"]},
"class":"money","retry":false,"next":"top up from $5 at /account, then repeat this call"}
class is one of auth, input, money,
rate, conflict, server. retry is true only when sending the
same request again can succeed.
From an agent (MCP)
An MCP server ships with the product: five tools — archscan_analyze,
archscan_status, archscan_fix, archscan_download,
archscan_account. Point your client at it:
{
"mcpServers": {
"archscan": {
"command": "python3",
"args": ["/opt/archscan/mcp/archscan_mcp.py"],
"env": { "ARCHSCAN_API_KEY": "ask_…", "ARCHSCAN_BASE": "https://neuromomen.com" }
}
}
}
Needs only python3 — no packages, no build step.
From a shell (CLI)
python3 cli/archscan.py login --key ask_… # stored in ~/.config/archscan (chmod 600)
python3 cli/archscan.py analyze project.zip --wait
python3 cli/archscan.py fix <job> --dry # price it
python3 cli/archscan.py fix <job> --wait # run it
python3 cli/archscan.py download <job> -o fixed.zip
Every command prints one line of JSON; a failure prints its class and a
next: line on stderr.
Keys and limits
A key has the same authority as your session: it can spend your tokens. It is shown once, stored hashed, never logged, and can be revoked on /account — revocation takes effect on the next call. One fix run at a time per account; per-run caps grow with the balance (150 findings / 6 rounds on the smallest, 1000 / 20 at 5M tokens).