The scoring server API
A small JSON API: send the trees of your files, get back a score, flags and refactoring hints.
https://krypton-prodserver-production.up.railway.app.Overview
| Method and path | Purpose |
|---|---|
GET /v1/health | Liveness for a host or load balancer. |
GET /v1/capabilities | What this server accepts, so a client can check compatibility before sending. |
POST /v1/score | Trees in, result out. Synchronous and stateless. |
POST /v1/order | File names, token counts and recent history in; the order to send the files in, or the order you already have, out. |
Requests and responses are JSON. A request body may be gzip-compressed. Every response carries an X-Request-Id header, repeated as request_id in the body, to quote when asking for support.
GET /v1/health
curl https://krypton-prodserver-production.up.railway.app/v1/health
# {"status": "ok"}
GET /v1/capabilities
Returns what the server accepts, for a client to check before sending anything.
curl https://krypton-prodserver-production.up.railway.app/v1/capabilities
{
"server_version": "0.1.0",
"wire_versions": [1],
"languages": { "python": [".py"], "javascript": [".js", ".jsx", ".mjs", ".cjs"], "typescript": [".ts", ".mts", ".cts"], "tsx": [".tsx"] },
"levels": ["relaxed", "standard", "strict"],
"detail_levels": ["summary"],
"allowed_config": ["allow_waivers", "detect_vendored_content", "vendored_path_globs", "generated_path_globs",
"generated_markers", "test_path_globs", "python_source_roots", "ts_path_aliases", "ts_base_url"],
"limits": { "max_body_bytes": 20971520, "max_files": 2000, "max_nodes_per_file": 500000, "max_nodes_per_request": 3000000 },
"policy": { /* which nodes carry a fingerprint or a mask; see Wire format */ }
}
detail_levels lists what this server serves. allowed_config lists the only settings a request may override: file selection and conventions. Thresholds, weights and caps are not on the list, so a client cannot change them.
POST /v1/score
Headers:
| Header | Value |
|---|---|
Content-Type | application/json |
Content-Encoding | Optional: gzip. Any other encoding is refused. |
The body is described in Wire format. A minimal call, with the request already built and compressed:
curl -sS https://krypton-prodserver-production.up.railway.app/v1/score \
-H "Content-Type: application/json" \
-H "Content-Encoding: gzip" \
--data-binary @request.json.gz
A request of about 65,000 lines is roughly 26 MB as JSON and 4.5 MB gzipped, so compress anything large.
POST /v1/order
Decides whether sending a prompt's files in Krypton's order would reuse more of a provider's prompt cache than your order, judged on the repository's own history. The client reads git on your machine and sends only file names, token counts and which files each recent commit touched: no source text, commit messages or authors.
{ "wire_version": 1,
"files": [ { "path": "src/config.py", "tokens": 812 }, ... ], // your order
"history": [ ["src/a.py", "src/b.py"], ["src/a.py"], ... ], // one list per commit, oldest first
"in_flux": ["src/b.py"] } // uncommitted files (optional)
The answer's result has action (keep or reorder), reason, order (yours when keep, the new one when reorder, so a caller can always send order as is) and a backtest summary.
The response
Scoring a file that cannot be scored is not an HTTP error: files too large, too wide or unparseable appear in errors and skipped_files and are left out of the score, exactly as the command line does.
{
"request_id": "9f2c1e04",
"server_version": "0.1.0",
"wire_version": 1,
"usage": { "files": 1, "nodes": 21, "ms": 18 },
"result": {
"purity_score": 100,
"check_conclusion": "success",
"flagged_file_count": 0,
"files": [
{ "filename": "src/a.py", "language": "python", "flagged": false, "flag_reason": null, "parse_error": false,
"functions": [ { "name": "252f10c83610ebca", "start_line": 1, "end_line": 4, "score": 1,
"max_depth": 1, "nested": false, "exempt_reason": null } ] }
],
"skipped_files": [],
"errors": {},
"hints": {},
"hint_regions": {},
"fragmentation_flagged": false,
"summary_markdown": "### Krypton Structural Review -- Purity Score: 100/100 ..."
}
}
- Names are fingerprints. A function's
namecomes back as the fingerprint the client sent. The client looks it up in its names book to show the real name; the server never knew it. detail.summary(the default) returns scores, flags, hints and the Markdown summary.fullalso returns the raw metric columns and is refused (403) unless the server was started to allow it, which a public server is not.- Flags and hints. Each flagged file carries a
flag_reason, andhintsmaps a function to refactoring advice. What the flags mean is in How it works.
Errors
Every error is JSON with the same shape:
{ "error": { "code": "invalid_tree", "message": "files[0].tree.parent[3] = 7 points forward",
"path": "files[0].tree.parent[3]", "request_id": "9f2c1e04" } }
| HTTP | code | When |
|---|---|---|
| 400 | invalid_json | The body is not JSON, or the gzip stream is bad. |
| 403 | detail_not_allowed | The detail level requested is not served by this server. |
| 404 / 405 | not_found, method_not_allowed | Unknown path or method. |
| 413 | too_large | Over a body, file or node limit (see below). |
| 415 | unsupported_media_type | Not application/json, or an unsupported Content-Encoding. |
| 422 | invalid_tree, invalid_request | The body does not follow the format: array lengths differ, a parent points forward, a range is outside its file, an unknown kind or language. path names the first problem. |
| 426 | unsupported_wire_version | The wire_version is not one the server speaks. |
| 429 | rate_limited | Over this address's per-minute limit. Retry-After says how many seconds to wait. |
| 503 | busy | The server is already scoring as many requests as it can and its waiting line is full. Retry-After says how many seconds to wait. |
| 500 | internal | A server fault. The body has the request_id and nothing else: no stack trace, no input. |
The tree is untrusted input. It is checked before anything is scored, and a malformed tree never reaches the engine. A server error is never the answer to a bad request.
Limits
| Limit | Value |
|---|---|
| Request body, as sent | 20 MB |
| Body after decompression | set by the server's memory, up to 256 MB (about 85 MB, some 275,000 lines, on a 512 MB server); capabilities reports it as max_decompressed_bytes |
| Files per request | 2,000 |
| Nodes per file | 500,000 |
| Nodes per request | 3,000,000 |
A request over its address's per-minute limit is answered with 429 and a Retry-After. The same numbers are in GET /v1/capabilities. Files the engine's own size rules skip (very large files, extremely long lines, single nodes with a huge number of children) are reported in errors, not refused.
Versioning
The request names its wire_version. A server answers 426 to a version it does not speak, and capabilities lists the versions it does. Adding an optional field does not change the version; changing the meaning of an existing one does.