Krypton
API reference

The scoring server API

A small JSON API: send the trees of your files, get back a score, flags and refactoring hints.

A small JSON APIHealth, capabilities, score and order.
Structure in, numbers outTrees and hashes go in; scores, flags and hints come back.
Stores nothingEach request is scored and forgotten.
Examples use the hosted server, https://krypton-prodserver-production.up.railway.app.

Overview

Method and pathPurpose
GET /v1/healthLiveness for a host or load balancer.
GET /v1/capabilitiesWhat this server accepts, so a client can check compatibility before sending.
POST /v1/scoreTrees in, result out. Synchronous and stateless.
POST /v1/orderFile 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:

HeaderValue
Content-Typeapplication/json
Content-EncodingOptional: 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 ..."
  }
}

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" } }
HTTPcodeWhen
400invalid_jsonThe body is not JSON, or the gzip stream is bad.
403detail_not_allowedThe detail level requested is not served by this server.
404 / 405not_found, method_not_allowedUnknown path or method.
413too_largeOver a body, file or node limit (see below).
415unsupported_media_typeNot application/json, or an unsupported Content-Encoding.
422invalid_tree, invalid_requestThe 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.
426unsupported_wire_versionThe wire_version is not one the server speaks.
429rate_limitedOver this address's per-minute limit. Retry-After says how many seconds to wait.
503busyThe server is already scoring as many requests as it can and its waiting line is full. Retry-After says how many seconds to wait.
500internalA 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

LimitValue
Request body, as sent20 MB
Body after decompressionset 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 request2,000
Nodes per file500,000
Nodes per request3,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.