{ "openapi": "3.1.0", "info": { "title": "Neurarch API", "version": "1.0.0", "summary": "A change pre-check for open-weight models over HTTP: what changed, what the job needs, whether a parallel layout is legal and balanced, and whether a serving config matches the model, before any GPU or traffic.", "description": "Deterministic: no endpoint here calls a language model. Every number is derived from the graph (and the Hugging Face config, when posted) and is labelled as derived, not measured. Human-readable reference: https://www.neurarch.com/developer. Use the www host: the apex answers /api with a 307, and curl -L and fetch drop the Authorization header across that hop. This document is checked against the live handler by scripts/openapi.test.ts, which fails when a documented response field stops being returned.", "contact": { "url": "https://www.neurarch.com/developer" } }, "servers": [ { "url": "https://www.neurarch.com", "description": "Hosted" } ], "tags": [ { "name": "pre-check", "description": "The four questions: what changed, what the job needs, is the layout legal and balanced, does the serving config match the model." }, { "name": "account", "description": "What was done under your own key." }, { "name": "research", "description": "Kept for agents that already call it. Not part of the pre-check, and it says in every response how weakly its ordering is supported." } ], "security": [{ "apiKey": [] }], "paths": { "/api/v1/check": { "post": { "operationId": "check", "tags": ["pre-check"], "summary": "The whole verdict for a graph, plus data fit, parallel layout and serving checks when asked", "description": "Five stages run in order (preflight, data, train, evaluate, deploy) and stop at the first blocker. Questions do not stop the walk over HTTP: they come back in `decision`. Each of `data`, `layout` and `serve` is optional and adds one report beside the verdict (`dataFit`, `layout`, `serve`). A `comfyWorkflow` with no `model` returns `{ comfy }` instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckRequest" } } } }, "responses": { "200": { "description": "The verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unverifiable" } } } }, "/api/v1/lint": { "post": { "operationId": "lint", "tags": ["pre-check"], "summary": "Just the structural rules that fired, with stable ids", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["model"], "properties": { "model": { "$ref": "#/components/schemas/Graph" } } } } } }, "responses": { "200": { "description": "Findings and a rolled-up verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LintResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unverifiable" } } } }, "/api/v1/plan": { "post": { "operationId": "plan", "tags": ["pre-check"], "summary": "A plan for one graph: size, memory, fit, cost, and against a base what changed", "description": "The API key is optional: anonymous callers are rate-limited by address. `share: true` stores the graph and returns a public /p/ URL; it is the only call here that stores a graph, and only when asked.", "security": [{ "apiKey": [] }, {}], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanRequest" } } } }, "responses": { "200": { "description": "The plan, as JSON and as text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unverifiable" }, "429": { "description": "Too many anonymous plans from this address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/activity": { "get": { "operationId": "activity", "tags": ["account"], "summary": "What was done on your account: keys, plans, agent-submitted runs, the outcome ledger", "description": "Accepts an API key or an app session token. Anything the schema cannot record comes back in `gaps` as a sentence, never as a zero. A lane's `status` says whether its rows can be read at all: `unavailable`, `absent`, `silent` or `active`.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/rank": { "post": { "operationId": "rank", "tags": ["research"], "summary": "Research: order k unexecuted designs (mostly abstains, and says so)", "description": "Which candidates cannot forward-pass is the calibrated part. Ordering two legal designs is weakly supported: the response carries `calibration` with the in-sample numbers behind that, and ties stay ties unless you pass your own `tieBreak`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankRequest" } } } }, "responses": { "200": { "description": "The ordering and its calibration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/TooLarge" }, "422": { "$ref": "#/components/responses/Unverifiable" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "A developer key, `nrk_...`, minted in the app under Settings, Developer API. Stored only as a SHA-256." } }, "responses": { "BadRequest": { "description": "The body is not the documented shape, or a field has an unreadable value. The error names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooLarge": { "description": "More than 2000 components (or more than 20 candidates on rank).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unverifiable": { "description": "The graph could not be read as a model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } } }, "Graph": { "type": "object", "description": "A model graph. Shapes carry no batch dimension: [3, 32, 32] is C, H, W. Connections may name layers by id or by name.", "required": ["components"], "properties": { "components": { "type": "array", "maxItems": 2000, "items": { "type": "object", "required": ["type"], "properties": { "id": { "type": "string" }, "type": { "type": "string", "examples": ["input", "embedding", "groupedQueryAttention", "linear"] }, "name": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } } }, "connections": { "type": "array", "items": { "type": "object", "required": ["from", "to"], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } } } } }, "CheckRequest": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/Graph" }, "config": { "type": "object", "additionalProperties": true, "description": "The Hugging Face config.json, when there is one. Used by `data` and `serve` for the declared context, vocab and quantization." }, "spec": { "type": "object", "additionalProperties": true, "description": "A change spec (what the edit is allowed to move). Answered as `change`, by the same function `plan` uses." }, "data": { "$ref": "#/components/schemas/DataSpec" }, "layout": { "$ref": "#/components/schemas/LayoutSpec" }, "serve": { "$ref": "#/components/schemas/ServeSpec" }, "comfyWorkflow": { "type": "object", "additionalProperties": true, "description": "A ComfyUI workflow in either save format, sent instead of `model`." } } }, "DataSpec": { "type": "object", "description": "What the job will feed the model. Snake or camel case. A present field that is not a positive integer is a 400, not ignored.", "properties": { "seq_len": { "type": "integer", "minimum": 1 }, "tokenizer_size": { "type": "integer", "minimum": 1, "description": "Alias: vocab_size." }, "num_classes": { "type": "integer", "minimum": 1, "description": "Alias: num_labels." }, "image_size": { "type": "integer", "minimum": 1 }, "channels": { "type": "integer", "minimum": 1, "description": "Alias: num_channels." } } }, "LayoutSpec": { "type": "object", "description": "How a training job is split across GPUs. Snake or camel case. Unknown keys are ignored; a known key with an unreadable value is a 400.", "required": ["micro_batch", "seq_len"], "properties": { "tp": { "type": "integer", "minimum": 1, "default": 1 }, "pp": { "type": "integer", "minimum": 1, "default": 1 }, "dp": { "type": "integer", "minimum": 1, "default": 1 }, "cp": { "type": "integer", "minimum": 1 }, "ep": { "type": "integer", "minimum": 1 }, "num_gpus": { "type": "integer", "minimum": 1 }, "gpu": { "type": "string", "description": "A card id or an unambiguous prefix: h100, l4, a100-80g. Default h100-sxm.", "examples": ["h100", "l4"] }, "micro_batch": { "type": "integer", "minimum": 1 }, "global_batch": { "type": "integer", "minimum": 1 }, "grad_accum": { "type": "integer", "minimum": 1 }, "seq_len": { "type": "integer", "minimum": 1 }, "schedule": { "type": "string", "enum": ["1f1b", "interleaved"] }, "virtual_stages": { "type": "integer", "minimum": 1 }, "layers_per_stage": { "type": "array", "items": { "type": "integer", "minimum": 1 } }, "kernel_stack": { "type": "string", "enum": ["eager", "fused"] }, "zero_stage": { "type": "integer", "enum": [0, 1, 2, 3] }, "fsdp": { "type": "boolean" }, "activation_checkpointing": { "type": "boolean" }, "fused_cross_entropy": { "type": "boolean", "description": "When true, the stage with the loss does not count the fp32 logits and their gradient." }, "embedding_on_first": { "type": "boolean" }, "head_on_last": { "type": "boolean" }, "qk_norm": { "type": "boolean" }, "seq_len_histogram": { "description": "[{len, count}], [[len, count]] or two-column CSV text. Enables the DP sequence-imbalance check.", "oneOf": [{ "type": "array" }, { "type": "string" }] } } }, "ServeSpec": { "type": "object", "description": "How the model is launched for inference. `command` is parsed; `args` (already parsed flags) wins key by key.", "properties": { "engine": { "type": "string", "enum": ["vllm", "sglang", "llamacpp"], "description": "Needed only when `command` does not say." }, "command": { "type": "string", "examples": ["vllm serve Qwen/Qwen3-8B -tp 4 --max-model-len 32768"] }, "args": { "type": "object", "additionalProperties": true }, "gpu": { "type": "string", "description": "A card id or an unambiguous prefix: h100, h200, b200, a100-80g, l40s, l4, a10g, t4." }, "gpus": { "type": "integer", "minimum": 1 }, "sampler": { "type": "object", "properties": { "temperature": { "type": "number" }, "top_p": { "type": "number" }, "top_k": { "type": "number" }, "repetition_penalty": { "type": "number" } } }, "tokenizer_config": { "type": "object", "additionalProperties": true }, "chat_template": { "type": "string" }, "generation_config": { "type": "object", "additionalProperties": true }, "model_id": { "type": "string", "examples": ["Qwen/Qwen3-8B"] }, "against": { "type": "object", "description": "A reference model (and its files) to compare the served one with.", "required": ["model"], "properties": { "model": { "$ref": "#/components/schemas/Graph" }, "config": { "type": "object", "additionalProperties": true }, "tokenizer_config": { "type": "object", "additionalProperties": true }, "chat_template": { "type": "string" }, "generation_config": { "type": "object", "additionalProperties": true }, "model_id": { "type": "string" } } } } }, "Skipped": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string" }, "reason": { "type": "string" } } } }, "CheckFinding": { "type": "object", "properties": { "stage": { "type": "string", "enum": ["preflight", "data", "train", "evaluate", "deploy"] }, "severity": { "type": "string", "enum": ["block", "warn"] }, "ruleId": { "type": "string", "description": "Present when the finding is a check. Each id has a page at /r/.html." }, "blocks": { "type": "boolean", "description": "Whether this finding stopped the walk, separate from severity. True on every top-level block; false on every finding inside provisionalStages, which stop nothing, and on a check that could not run." }, "title": { "type": "string" }, "detail": { "type": "string" }, "fix": { "type": "string" } } }, "CheckResponse": { "type": "object", "required": ["verdict", "designVerdict", "verdictSources", "verdictParts", "outcome", "summary", "stoppedAt", "findings", "stages"], "properties": { "verdict": { "type": "string", "enum": ["block", "warn", "ask", "ok"], "description": "The worst of designVerdict and every data, layout, serve or spec block the request carried, ordered block > ask > warn > ok. A launch the serve check blocks is block here whatever the graph says. Gate on this field." }, "designVerdict": { "type": "string", "enum": ["block", "warn", "ask", "ok"], "description": "The graph's own verdict: the worst status any stage reported. Equal to verdict on a request with no blocks." }, "verdictSources": { "type": "array", "items": { "type": "string", "enum": ["design", "serve", "layout", "data", "change"] }, "description": "The parts whose own verdict equals verdict, in this order: design, serve, layout, data, change." }, "verdictParts": { "type": "object", "description": "Each answered part's own verdict. A block is block if any finding is a blocker, warn if any is a warning, ok otherwise; info findings never move it. A part the request did not carry is absent.", "properties": { "design": { "type": "string", "enum": ["block", "warn", "ask", "ok"] }, "serve": { "type": "string", "enum": ["block", "warn", "ok"] }, "layout": { "type": "string", "enum": ["block", "warn", "ok"] }, "data": { "type": "string", "enum": ["block", "warn", "ok"] }, "change": { "type": "string", "enum": ["block", "warn", "ok"] } } }, "outcome": { "type": "string", "enum": ["complete", "blocked", "needs_input"] }, "summary": { "type": "string" }, "stoppedAt": { "type": ["string", "null"] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/CheckFinding" } }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "status": { "type": "string" }, "headline": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "description": "Stage-specific payload; fields are only ever added. Deploy carries suitability (YES, MAYBE, NO or null when no verified op table is held for the target), suitabilityReason, backend (supported share, partitions and unsupported layers, with the upstream table's URL), quantized (int8 size from the quantizable share), onnx (minimum opset and which layer sets it) and kvCache (vLLM-style fit for a decoder LM on a GPU target); score is kept but no longer leads. Evaluate carries testN, interval (95% Wilson), minimumDetectableDifference, headlineMetric and imbalanced. Data carries datasetMeta when a Hugging Face dataset's metadata was read." } } } }, "provisionalStages": { "type": "array", "description": "Graph-only stages computed after the walk stopped: Data's contract check when a dataset is wired, and Deploy's target analysis. Each carries its own findings. Never counted in verdict, outcome, stoppedAt or findings, so a caller that ignores this field gets the answer it got before.", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "status": { "type": "string" }, "headline": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "findings": { "type": "array", "description": "Same shape as the top-level findings; ruleId and fix appear where the finding has them.", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "severity": { "type": "string", "enum": ["block", "warn"] }, "title": { "type": "string" }, "detail": { "type": "string" } } } } } } }, "decision": { "type": "object", "description": "Present when something is the human's call. Surface it; do not answer it.", "properties": { "question": { "type": "string" }, "because": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } } }, "dataFit": { "$ref": "#/components/schemas/DataFitReport" }, "layout": { "$ref": "#/components/schemas/LayoutReport" }, "serve": { "$ref": "#/components/schemas/ServeReport" }, "change": { "type": "object", "additionalProperties": true, "description": "Present when `spec` was sent." } } }, "DataFitReport": { "type": "object", "properties": { "checked": { "type": "array", "items": { "type": "string" } }, "skipped": { "$ref": "#/components/schemas/Skipped" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": ["block", "warn", "info"] }, "title": { "type": "string" }, "detail": { "type": "string" }, "fix": { "type": "string" } } } }, "contract": { "type": "object", "description": "What the model accepts, and where each number was read from.", "properties": { "vocabSize": { "type": ["integer", "null"] }, "maxPositions": { "type": ["integer", "null"] }, "positionKind": { "type": ["string", "null"] }, "numLabels": { "type": ["integer", "null"] }, "imageSize": { "type": ["integer", "null"] }, "channels": { "type": ["integer", "null"] }, "source": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "LayoutReport": { "type": "object", "description": "Derived from the graph, not measured. `basis` states how.", "properties": { "checked": { "type": "array", "items": { "type": "string" } }, "skipped": { "$ref": "#/components/schemas/Skipped" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": ["block", "warn", "info"] }, "title": { "type": "string" }, "detail": { "type": "string" }, "fix": { "type": "string" } } } }, "resolved": { "type": "object", "properties": { "gpu": { "type": ["string", "null"] }, "gpuMemoryGb": { "type": ["number", "null"] }, "worldSize": { "type": "integer" }, "microbatchesPerStep": { "type": ["integer", "null"] }, "globalBatch": { "type": ["integer", "null"] }, "blocks": { "type": "integer" }, "layersPerStage": { "type": ["array", "null"], "items": { "type": "integer" } }, "schedule": { "type": "string", "enum": ["1f1b", "interleaved"] }, "virtualStages": { "type": "integer" }, "zeroStage": { "type": "integer" } } }, "stages": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "layers": { "type": "object", "properties": { "first": { "type": "integer" }, "last": { "type": "integer" }, "count": { "type": "integer" }, "extras": { "type": "array", "items": { "type": "string" } } } }, "params": { "type": "number" }, "estMsPerMicrobatch": { "type": ["number", "null"] }, "lossLogitsGb": { "type": "number" }, "peakGbPerGpu": { "type": "number" }, "peakGbUpperPerGpu": { "type": "number" }, "fitsGpu": { "type": "string" } } } }, "imbalance": { "type": "object", "properties": { "costBasis": { "type": "string", "enum": ["time", "flops"] }, "maxOverMean": { "type": "number" }, "slowestStage": { "type": "integer" }, "estStepSlowdown": { "type": "number", "description": "At this layout's own microbatch count." }, "asymptoticSlowdown": { "type": "number", "description": "As microbatches go to infinity; overstates at small counts." }, "step": { "type": "object", "properties": { "microbatches": { "type": ["integer", "null"] }, "formula": { "type": "string" }, "currentMs": { "type": ["number", "null"] }, "balancedMs": { "type": ["number", "null"] } } }, "rebalanced": { "type": ["object", "null"], "properties": { "layersPerStage": { "type": "array", "items": { "type": "integer" } }, "maxOverMean": { "type": "number" }, "estStepSpeedup": { "type": "number" }, "asymptoticSpeedup": { "type": "number" } } } } }, "bubble": { "type": ["object", "null"], "properties": { "fraction": { "type": "number" }, "microbatches": { "type": ["integer", "null"] } } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "basis": { "type": "string" } } }, "ServeReport": { "type": "object", "description": "Predicted from config, flags and card, not measured. `basis` states how.", "properties": { "engine": { "type": "string", "enum": ["vllm", "sglang", "llamacpp"] }, "resolved": { "type": "object", "properties": { "gpu": { "type": ["string", "null"] }, "gpuMemoryGb": { "type": ["number", "null"] }, "gpus": { "type": "integer" }, "tp": { "type": "integer" }, "pp": { "type": "integer" }, "dp": { "type": "integer" }, "dtype": { "type": "string" }, "quant": { "type": ["string", "null"] }, "kvCacheDtype": { "type": "string" }, "servedLen": { "type": ["integer", "null"] }, "derivedMaxLen": { "type": ["integer", "null"] }, "engineVersion": { "type": ["string", "null"] }, "engineVersionAssumed": { "type": "boolean" }, "defaultsAssumed": { "type": "array", "items": { "type": "string" } } } }, "checked": { "type": "array", "items": { "type": "string" } }, "skipped": { "$ref": "#/components/schemas/Skipped" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "area": { "type": "string" }, "severity": { "type": "string", "enum": ["block", "warn", "info"] }, "title": { "type": "string" }, "detail": { "type": "string" }, "fix": { "type": "string" } } } }, "memory": { "type": ["object", "null"], "properties": { "weightsGbPerGpu": { "type": "number" }, "budgetGbPerGpu": { "type": "number" }, "kvBytesPerTokenPerGpu": { "type": "number" }, "kvCapacityGbPerGpu": { "type": "number" }, "tokenCapacity": { "type": "number" }, "maxConcurrentFullLength": { "type": ["number", "null"] }, "method": { "type": "string" }, "notCounted": { "type": "array", "items": { "type": "string" } } } }, "change": { "type": ["object", "null"], "description": "Present when `against` was sent." }, "basis": { "type": "string" } } }, "LintResponse": { "type": "object", "properties": { "verdict": { "type": "string", "enum": ["block", "warn", "pass"] }, "counts": { "type": "object", "properties": { "block": { "type": "integer" }, "warn": { "type": "integer" }, "info": { "type": "integer" } } }, "findings": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "severity": { "type": "string", "enum": ["block", "warn", "info"] }, "message": { "type": "string" }, "componentName": { "type": "string" }, "componentType": { "type": "string" } } } }, "provenance": { "type": "array", "description": "For each rule that fired and has a published measurement, the measurement.", "items": { "type": "object", "additionalProperties": true } }, "inferred": { "type": "object", "description": "Present only when some edges were assumed by our .py importer rather than stated by the source." } } }, "PlanRequest": { "type": "object", "required": ["model"], "properties": { "model": { "$ref": "#/components/schemas/Graph" }, "base": { "$ref": "#/components/schemas/Graph" }, "config": { "type": "object", "additionalProperties": true, "description": "The changed model's Hugging Face config.json. Read only together with `base_config`." }, "base_config": { "type": "object", "additionalProperties": true }, "spec": { "type": "object", "additionalProperties": true }, "policy": { "type": "object", "additionalProperties": true, "description": "Your .neurarch.yml lines. They can only make the verdict stricter." }, "attention": { "type": "string", "enum": ["sdpa", "flash", "eager"], "default": "sdpa" }, "seq_len": { "type": "integer", "minimum": 1 }, "share": { "type": "boolean", "description": "Store the graph and return a public /p/ URL." }, "source": { "type": "object", "additionalProperties": true, "description": "Where the call came from (repository, pull request, target). Optional." } } }, "PlanResponse": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "version": { "type": "integer" }, "summary": { "type": "string" }, "model": { "type": "object", "properties": { "name": { "type": "string" }, "layers": { "type": "integer" }, "params": { "type": "number" }, "inputShape": { "type": ["array", "null"] }, "outputShape": { "type": ["array", "null"] }, "fingerprint": { "type": "string" } } }, "run": { "type": "object", "additionalProperties": true }, "cost": { "type": "object", "properties": { "estCostUsd": { "type": ["number", "null"] }, "estTrainSec": { "type": ["number", "null"] }, "peakGb": { "type": ["number", "null"] }, "peakGbUpper": { "type": ["number", "null"] }, "gpuVerdict": { "type": ["string", "null"] }, "smallestFitGpu": { "type": ["string", "null"] }, "smallestSafeGpu": { "type": ["string", "null"] }, "seqLen": { "type": ["integer", "null"] }, "assumptions": { "type": "array", "items": { "type": "string" } } } }, "diff": { "type": ["object", "null"], "description": "Present with `base`: what changed and how far it reaches." }, "policy": { "type": ["object", "null"] }, "history": { "type": ["array", "null"], "description": "Your own prior outcomes for this structure. Keyed calls only." }, "change": { "type": ["object", "null"] } } }, "text": { "type": "string" }, "markdown": { "type": "string" }, "url": { "type": "string", "description": "With share: true." }, "id": { "type": "string", "description": "With share: true." } } }, "Lane": { "type": "object", "properties": { "status": { "type": "string", "enum": ["unavailable", "absent", "silent", "active"] }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "ActivityResponse": { "type": "object", "properties": { "windowDays": { "type": "integer" }, "generatedAt": { "type": "string", "format": "date-time" }, "keys": { "type": "object", "properties": { "status": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": ["string", "null"] }, "revoked": { "type": "boolean" } } } } } }, "repositories": { "type": "array", "items": { "type": "string" } }, "plans": { "allOf": [{ "$ref": "#/components/schemas/Lane" }], "properties": { "status": { "type": "string" }, "rows": { "type": "array" }, "unattributedInWindow": { "type": "integer" } } }, "runs": { "allOf": [{ "$ref": "#/components/schemas/Lane" }], "properties": { "status": { "type": "string" }, "rows": { "type": "array" }, "jobsInWindow": { "type": "integer" }, "sourceTagged": { "type": "integer" } } }, "ledger": { "$ref": "#/components/schemas/Lane" }, "prevented": { "$ref": "#/components/schemas/Lane" }, "totals": { "type": "object", "properties": { "plansWithRepository": { "type": "integer" }, "pullRequestsPlanned": { "type": "integer" }, "repositories": { "type": "integer" }, "runsSubmitted": { "type": "integer" }, "runsCompleted": { "type": "integer" }, "outcomesRecorded": { "type": "integer" }, "estCostUsd": { "type": ["number", "null"], "description": "Only money somebody reported. Never derived from a GPU price." }, "activeKeys": { "type": "integer" } } }, "gaps": { "type": "array", "items": { "type": "string" } } } }, "RankRequest": { "type": "object", "required": ["candidates"], "properties": { "candidates": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": ["model"], "properties": { "id": { "type": "string" }, "model": { "$ref": "#/components/schemas/Graph" } } } }, "tieBreak": { "type": "string", "enum": ["none", "cost", "params"], "default": "none" } } }, "RankResponse": { "type": "object", "properties": { "ranked": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rank": { "type": "integer" }, "measuredRank": { "type": "integer" }, "tier": { "type": "string", "enum": ["legal", "blocked"] }, "tiedWith": { "type": "integer" }, "blocking": { "type": "integer" }, "warnings": { "type": "integer" }, "otherStageBlockers": { "type": "array", "items": { "type": "string" } }, "params": { "type": ["number", "null"] }, "estCostUsd": { "type": ["number", "null"] }, "reasons": { "type": "array", "items": { "type": "string" } } } } }, "recommended": { "type": ["string", "null"], "description": "Null whenever the top rank is shared." }, "tieBreak": { "type": "object", "properties": { "rule": { "type": "string" }, "decided": { "type": "integer" } } }, "calibration": { "type": "object", "properties": { "exclusion": { "type": "object", "additionalProperties": true }, "ordering": { "type": "object", "additionalProperties": true } } } } } } } }