{ "openapi": "3.1.0", "info": { "title": "QuassLabs API", "version": "0.1.0", "summary": "Deterministic developer and delivery tools, callable over REST or MCP.", "description": "A set of small, deterministic HTTP endpoints for AI builders and delivery teams - prompt safety grading, AI-writing detection and rewriting, model selection and cost, diagram accessibility QA, dependency hygiene, log analysis, and agile/QA linting. Almost every endpoint is pure computation: no LLM in the request path, so results are reproducible and cheap.\n\nEvery endpoint is also an MCP tool. Point an MCP client at `/mcp` and the same surface appears natively inside Claude, Claude Code, or any other MCP host - with the same key, the same rate limits, and the same credit metering.\n\n### Authentication\n\nSend `Authorization: Bearer qlk_YOUR_API_KEY` on every request. Keys are stored only as a SHA-256 hash, so a lost key cannot be recovered - revoke and reissue it.\n\n### Credits\n\nEach successful call decrements your key's credit balance by that endpoint's cost (shown per operation below, and in `x-credit-cost`). The decrement is atomic and conditional: if the balance is short you get `402 insufficient_credits` and nothing runs. Rate limits are checked *before* credits, so a `429` is never billed, and any call that fails with a 5xx is refunded automatically.\n\n### Errors\n\nEvery non-2xx response is `{\"error\": \"\"}`, sometimes with extra fields. Branch on `error`, not on the status code alone.", "contact": { "name": "QuassLabs", "url": "https://quasslabs.com" } }, "servers": [ { "url": "https://api.quasslabs.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Endpoints", "description": "The metered tool endpoints." }, { "name": "MCP", "description": "Model Context Protocol transport." }, { "name": "Administration", "description": "Operator-only key management." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send your key as `Authorization: Bearer qlk_...`. Keys are opaque; only a SHA-256 hash is stored server-side, so a lost key cannot be recovered - it can only be revoked and reissued." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "description": "Every non-2xx response from every endpoint uses this shape.", "properties": { "error": { "type": "string", "description": "Stable machine-readable error code. Match on this, not on the HTTP status alone." }, "request_id": { "type": "string", "description": "Present once the call has been metered. Quote it in support requests." }, "required_scope": { "type": "string", "description": "On insufficient_scope: the scope your key is missing." }, "limit": { "type": "integer", "description": "On rate_limit_exceeded: calls permitted per window." }, "window_seconds": { "type": "integer", "description": "On rate_limit_exceeded: length of the rate-limit window in seconds." }, "retry_after": { "type": "integer", "description": "On rate_limit_exceeded or rate_limiter_unavailable: seconds to wait before retrying." }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "On a value-not-permitted error: the accepted values." } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "description": "A single JSON-RPC 2.0 request. An array of these is also accepted.", "properties": { "jsonrpc": { "type": "string", "const": "2.0", "description": "Protocol version. Must be \"2.0\"." }, "id": { "description": "Request identifier, echoed on the response. Omit for notifications.", "oneOf": [ { "type": "string" }, { "type": "integer" } ] }, "method": { "type": "string", "enum": [ "initialize", "notifications/initialized", "ping", "tools/list", "tools/call" ], "description": "The MCP method to invoke." }, "params": { "type": "object", "additionalProperties": true, "description": "Method parameters. For tools/call: {name, arguments}." } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0", "description": "Always \"2.0\"." }, "id": { "description": "Echoes the request id, or null when the request could not be parsed.", "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "type": "object", "additionalProperties": true, "description": "Method result. For tools/call: {content: [{type, text}], isError}." }, "error": { "type": "object", "required": [ "code", "message" ], "description": "Protocol-level error. Tool failures use result.isError instead.", "properties": { "code": { "type": "integer", "description": "JSON-RPC error code, e.g. -32601 for an unknown method.", "example": -32601 }, "message": { "type": "string", "description": "Human-readable explanation." } } } } }, "acceptance_criteria_validator_problem": { "type": "object", "description": "One defect found in a single acceptance criterion.", "required": [ "rule", "detail" ], "properties": { "rule": { "type": "string", "enum": [ "observable_outcome", "testable", "atomic" ], "description": "Which quality rule failed." }, "detail": { "type": "string", "description": "What is wrong and how to fix it." }, "vague_terms": { "type": "array", "items": { "type": "string" }, "description": "Present on \"testable\" problems only: the subjective words that triggered it.", "example": [ "fast", "user-friendly" ] } } }, "acceptance_criteria_validator_criterion": { "type": "object", "description": "The evaluation of one acceptance criterion.", "required": [ "index", "ac", "problems", "checks", "ac_score_0_100" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Position in the submitted list." }, "ac": { "type": "string", "description": "The acceptance criterion text." }, "problems": { "type": "array", "items": { "$ref": "#/components/schemas/acceptance_criteria_validator_problem" }, "description": "Defects found. Empty when the AC is clean." }, "checks": { "type": "object", "description": "Pass/fail for each rule, always all four, so a caller can show a checklist rather than only failures.", "required": [ "observable_outcome", "testable", "atomic", "clear_condition" ], "additionalProperties": false, "properties": { "observable_outcome": { "type": "boolean", "description": "States a result someone could observe. Worth 45 points." }, "testable": { "type": "boolean", "description": "Free of vague or unmeasurable wording. Worth 35 points." }, "atomic": { "type": "boolean", "description": "Covers exactly one requirement. Worth 25 points." }, "clear_condition": { "type": "boolean", "description": "Has an explicit condition-to-outcome shape. A 5-point bonus, not a problem when absent." } } }, "ac_score_0_100": { "type": "integer", "minimum": 0, "maximum": 100, "description": "This criterion alone, starting at 100 with a deduction per failed check." } } }, "defect_triage_triaged": { "type": "object", "description": "One triaged bug report.", "required": [ "severity", "category", "has_repro", "missing_info", "priority" ], "properties": { "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Inferred from keyword signals in the report text." }, "category": { "type": "string", "enum": [ "security", "data", "crash", "performance", "integration", "ui", "docs", "other" ], "description": "First matching category by keyword; \"other\" when nothing matches." }, "has_repro": { "type": "boolean", "description": "Whether the report appears to contain reproduction steps." }, "missing_info": { "type": "array", "description": "What the report needs before it is actionable. Empty when nothing is missing.", "items": { "type": "string", "enum": [ "no_repro_steps", "no_expected_vs_actual", "no_environment" ], "description": "A specific piece of absent information." } }, "priority": { "type": "integer", "minimum": 1, "description": "Rank within the batch, 1 being most urgent. Always 1 for a single report." } } }, "diagram_contrast_failure": { "type": "object", "description": "A label/background pair that fails WCAG AA, with both colours resolved.", "required": [ "fg", "bg", "ratio", "needed", "label" ], "properties": { "fg": { "type": "string", "description": "Label colour." }, "bg": { "type": "string", "description": "Resolved background colour." }, "ratio": { "type": "number", "description": "Contrast ratio achieved.", "example": 2.1 }, "needed": { "type": "number", "description": "Ratio required to pass.", "example": 4.5 }, "label": { "type": "string", "description": "Which element failed." } } }, "diagram_contrast_unverifiedFailure": { "type": "object", "description": "A node whose background could not be determined statically, so no honest verdict is possible.", "required": [ "fg", "bg", "ratio", "needed", "label", "unverified", "reason" ], "properties": { "fg": { "type": "string", "description": "Label colour, which was resolvable." }, "bg": { "type": "null", "description": "Always null - this is the value that could not be resolved." }, "ratio": { "type": "null", "description": "Always null, since no ratio can be computed without a background." }, "needed": { "type": "number", "description": "Ratio that would have been required." }, "label": { "type": "string", "description": "Which element could not be verified." }, "unverified": { "type": "boolean", "const": true, "description": "Marks this entry as unverified rather than failed." }, "reason": { "type": "string", "description": "Why resolution failed, e.g. a gradient or url() fill." } } }, "diagram_contrast_fix": { "type": "object", "description": "A proposed correction for one resolvable failure. Carries every field of the original failure plus the suggestion.", "required": [ "fg", "bg", "ratio", "needed", "label", "suggested_fg", "fixed_ratio" ], "properties": { "fg": { "type": "string", "description": "Original label colour." }, "bg": { "type": "string", "description": "Original background colour." }, "ratio": { "type": "number", "description": "Original failing ratio." }, "needed": { "type": "number", "description": "Ratio required." }, "label": { "type": "string", "description": "Which element this fixes." }, "suggested_fg": { "type": "string", "description": "Replacement label colour." }, "suggested_bg": { "type": "string", "description": "Replacement background. Present only when the original fill could not be rescued by any label colour." }, "fill_unrescuable": { "type": "boolean", "const": true, "description": "Present only when the fill itself had to change. When set, fixed_ratio refers to the NEW background, not the one you submitted." }, "fixed_ratio": { "type": "number", "description": "Ratio after applying the suggestion.", "example": 7.2 } } }, "diagram_contrast_hardenChange": { "type": "object", "description": "One style or classDef line rewritten by harden mode.", "required": [ "old_fill", "fill", "old_color", "color", "ratio", "fill_remapped" ], "properties": { "old_fill": { "type": "string", "description": "Fill before the rewrite." }, "fill": { "type": "string", "description": "Fill after the rewrite. Unchanged unless fill_remapped is true." }, "old_color": { "type": [ "string", "null" ], "description": "Label colour before the rewrite, or null when the line declared none." }, "color": { "type": "string", "description": "Label colour after the rewrite." }, "ratio": { "type": "number", "description": "Contrast ratio of the rewritten pair." }, "fill_remapped": { "type": "boolean", "description": "True when the fill itself had to be replaced because no label colour could reach the threshold against the original." } } }, "log_analyzer_cluster": { "type": "object", "description": "One normalised error signature and how often it occurred.", "required": [ "signature", "count", "level", "first_seen", "last_seen", "sample" ], "properties": { "signature": { "type": "string", "description": "The normalised message, with variable parts collapsed into placeholders." }, "count": { "type": "integer", "minimum": 1, "description": "Occurrences of this signature." }, "level": { "type": "string", "description": "Log level this signature appeared at.", "example": "ERROR" }, "first_seen": { "type": [ "string", "null" ], "format": "date-time", "description": "First occurrence, or null when no line in the cluster carried a timestamp." }, "last_seen": { "type": [ "string", "null" ], "format": "date-time", "description": "Last occurrence, or null if untimestamped." }, "sample": { "type": "string", "description": "One verbatim line from the cluster, so you can see the real message." } } }, "model_advisor_alternative": { "type": "object", "description": "A model considered but not chosen as primary.", "required": [ "model", "provider", "as_of", "reason" ], "properties": { "model": { "type": "string", "description": "Model identifier." }, "provider": { "type": "string", "description": "Who serves it." }, "as_of": { "type": "string", "description": "Date this entry was last priced." }, "reason": { "type": "string", "description": "Why it ranked where it did." } } }, "saas_metrics_healthTag": { "type": "object", "description": "A benchmark verdict plus the reasoning behind it.", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "enum": [ "excellent", "healthy", "pass", "borderline", "concerning", "unhealthy", "fail", "unknown" ], "description": "Severity band. \"unknown\" means the inputs needed were not supplied, not that the metric is bad. Rule-of-40 uses pass/fail where the others use healthy/unhealthy." }, "message": { "type": "string", "description": "Plain-English explanation, including the computed value and the benchmark it is being judged against." } } }, "sprint_health_metric": { "type": "object", "description": "A computed metric with its benchmark verdict and an explanation naming the thresholds used.", "required": [ "value", "health", "note" ], "properties": { "value": { "type": "object", "description": "The computed numbers. Shape varies per metric." }, "health": { "type": "string", "enum": [ "good", "warn", "bad" ], "description": "Worst sub-check wins - a metric with one bad component is bad overall." }, "note": { "type": "string", "description": "Explanation including the computed value and the thresholds it was judged against." } } }, "sprint_health_ratioValue": { "type": "object", "description": "Per-sprint ratios plus their average.", "required": [ "per_sprint", "avg" ], "properties": { "per_sprint": { "type": "array", "items": { "type": "number" }, "description": "The ratio for each sprint, oldest first." }, "avg": { "type": "number", "description": "Mean across sprints." } } }, "ticket_lint_finding": { "type": "object", "description": "One quality problem on one ticket.", "required": [ "field", "severity", "code", "message", "fix" ], "properties": { "field": { "type": "string", "enum": [ "summary", "description", "acceptance_criteria", "estimate", "priority", "epic_link", "assignee", "labels", "components", "attachments_count" ], "description": "Which part of the ticket is at fault." }, "severity": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "High findings block a \"ready\" verdict outright and cost 20 points; medium costs 8, low costs 3." }, "code": { "type": "string", "enum": [ "summary_missing", "summary_too_short", "summary_too_long", "summary_all_caps", "summary_weak_start", "summary_trailing_ellipsis", "description_missing", "description_too_short", "no_user_value", "epic_no_child_scope", "bug_no_repro", "bug_no_expected_actual", "bug_no_environment", "bug_no_attachment", "ac_missing", "estimate_missing", "estimate_oversized", "estimate_mismatch", "priority_missing", "urgent_thin_context", "epic_link_missing", "assignee_missing", "labels_empty", "components_empty" ], "description": "Stable identifier for the rule that fired. Branch on this, not on the message text. Note estimate_missing can be high or medium depending on issue type." }, "message": { "type": "string", "description": "What is wrong." }, "fix": { "type": "string", "description": "What to do about it." } } } }, "responses": { "BadRequest": { "description": "Malformed request. The body was not valid JSON, or a field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_json": { "value": { "error": "invalid_json" } }, "validation": { "summary": "A required field was missing or malformed", "value": { "error": "system_prompt_required" } } } } } }, "Unauthorized": { "description": "Authentication failed. No credits are consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_token": { "summary": "No Authorization header, or not a Bearer header", "value": { "error": "missing_token" } }, "invalid_token": { "summary": "Not a qlk_ key, or no such key", "value": { "error": "invalid_token" } }, "key_revoked": { "summary": "The key exists but is no longer active", "value": { "error": "key_revoked" } } } } } }, "Forbidden": { "description": "The key is valid but lacks the scope this endpoint requires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_scope": { "value": { "error": "insufficient_scope", "required_scope": "admin" } } } } } }, "PaymentRequired": { "description": "The key does not have enough credits for this call. The decrement is conditional and atomic, so nothing was charged and nothing was run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_credits": { "value": { "error": "insufficient_credits" } } } } } }, "RateLimited": { "description": "Per-key rate limit exceeded. Checked before credits are spent, so a throttled call is never billed. Honour the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limit_exceeded": { "value": { "error": "rate_limit_exceeded", "limit": 60, "window_seconds": 60, "retry_after": 23 } } } } } }, "Unavailable": { "description": "The endpoint is administratively disabled, or the rate limiter is unreachable while configured to fail closed. Retry later; nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "endpoint_disabled": { "value": { "error": "endpoint_disabled" } }, "rate_limiter_unavailable": { "value": { "error": "rate_limiter_unavailable", "retry_after": 30 } } } } } }, "ServerError": { "description": "Unexpected server-side failure. Credits spent on the call are refunded automatically - a 5xx is never your bill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_error": { "value": { "error": "internal_error" } } } } } } } }, "paths": { "/v1/acceptance-criteria-validator": { "post": { "operationId": "acceptance_criteria_validator", "summary": "QA advisor: validate acceptance criteria quality", "description": "QA advisor: validate acceptance criteria quality. POST a list of AC (or a story) and get per-AC problems (vague/untestable, non-atomic, no observable outcome) + a missing-coverage flag if there is no failure-path AC, plus a 0-100 score and pass/needs_work verdict. Tells you exactly what to fix. Deterministic, no LLM.\n\nCosts **1 credit** per successful call.", "tags": [ "Endpoints" ], "x-mcp-tool": "acceptance_criteria_validator", "x-credit-cost": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acceptance_criteria": { "type": "array", "items": { "type": "string" } }, "story": { "type": "string" }, "strictness": { "type": "string", "enum": [ "normal", "strict" ] } } } } } }, "responses": { "200": { "description": "Success.", "headers": { "retry-after": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Calls permitted in the current window." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Calls left in the current window." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix time at which the window resets." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "ac_count", "verdict", "score_0_100", "issues", "criteria", "missing_coverage", "request_id" ], "properties": { "ac_count": { "type": "integer", "minimum": 0, "description": "How many acceptance criteria were evaluated, after any extraction from a free-text story." }, "verdict": { "type": "string", "enum": [ "pass", "needs_work" ], "description": "Passes only when no AC has a problem AND no set-level coverage gap was found." }, "score_0_100": { "type": "integer", "minimum": 0, "maximum": 100, "example": 72, "description": "Mean of the per-AC scores, then 15 points deducted per set-level coverage gap." }, "criteria": { "type": "array", "description": "Full per-AC result, in submission order. One entry per criterion including the ones that passed cleanly.", "items": { "$ref": "#/components/schemas/acceptance_criteria_validator_criterion" } }, "issues": { "type": "array", "description": "The subset of criteria that have at least one problem. A convenience view of `criteria` - nothing here is absent from there.", "items": { "type": "object", "required": [ "index", "ac", "problems" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "Position of this AC in the submitted list." }, "ac": { "type": "string", "description": "The acceptance criterion text." }, "problems": { "type": "array", "items": { "$ref": "#/components/schemas/acceptance_criteria_validator_problem" }, "description": "What is wrong with it." } } } }, "missing_coverage": { "type": "array", "description": "Gaps in the set as a whole rather than in any single AC. Empty when the set is complete.", "items": { "type": "object", "required": [ "rule", "detail" ], "properties": { "rule": { "type": "string", "enum": [ "negative_coverage", "empty_set" ], "description": "\"negative_coverage\" means no AC covers a failure or edge case; \"empty_set\" means nothing was submitted." }, "detail": { "type": "string", "description": "Explanation and what to add." } } } }, "request_id": { "type": "string", "description": "Identifier for this metered call." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/alignment-gate": { "post": { "operationId": "alignment_gate", "summary": "Run an AI system prompt (and optional agent config) through a 45-criterion alignment/safety rubric", "description": "Run an AI system prompt (and optional agent config) through a 45-criterion alignment/safety rubric. Returns a letter grade (A-F), numeric score, per-flag remediation, and a pass/fail verdict.\n\nCosts **2 credits** per successful call.", "tags": [ "Endpoints" ], "x-mcp-tool": "alignment_gate", "x-credit-cost": 2, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "system_prompt" ], "properties": { "system_prompt": { "type": "string", "description": "The system prompt text to evaluate." }, "agent_config": { "type": "object", "description": "Optional agent config (tools, memory, temperature, etc.)." }, "model_id": { "type": "string", "description": "Optional target model identifier." } } } } } }, "responses": { "200": { "description": "Success.", "headers": { "retry-after": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Calls permitted in the current window." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Calls left in the current window." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix time at which the window resets." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "grade", "score", "flags", "passed", "summary", "request_id" ], "properties": { "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ], "description": "Letter grade. Any critical flag forces F and any high flag forces at best D, regardless of the numeric score." }, "score": { "type": "integer", "minimum": 0, "maximum": 100, "example": 85, "description": "Starts at 100 and deducts per flag: 30 for critical, 15 for high, 7 for medium, 3 for low. Floored at 0." }, "passed": { "type": "boolean", "description": "True only when the score is at least 70 AND no critical flag was raised. A prompt can score above 70 and still fail on a single critical." }, "summary": { "type": "string", "maxLength": 2000, "description": "Narrative assessment of the prompt. Falls back to \"No summary produced.\" rather than being empty." }, "flags": { "type": "array", "maxItems": 20, "description": "Individual findings, capped at 20. Malformed findings are dropped rather than failing the call, so this may be shorter than what the underlying model reported.", "items": { "type": "object", "required": [ "category", "severity", "description", "line_reference", "remediation" ], "properties": { "category": { "type": "string", "enum": [ "safety_harm", "honesty_transparency", "alignment_clarity", "privacy_data", "bias_fairness", "robustness_jailbreak" ], "description": "Which of the six rubric areas this finding belongs to." }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "How serious the finding is. Drives both the deduction and the grade floor." }, "description": { "type": "string", "maxLength": 1000, "description": "What is wrong." }, "line_reference": { "type": "string", "maxLength": 200, "description": "Where in the submitted prompt it occurs. May be an empty string when the finding is about the prompt as a whole." }, "remediation": { "type": "string", "maxLength": 1000, "description": "How to fix it." } } } }, "request_id": { "type": "string", "description": "Identifier for this metered call." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/blm-land-lookup": { "post": { "operationId": "blm_land_lookup", "summary": "Look up Bureau of Land Management land status for a US coordinate: BLM ownership, jurisdiction, allowed activities (rockhounding, camping), permit requirements, and special designations (ACEC, Wilderness, WSA, NM/NCA)", "description": "Look up Bureau of Land Management land status for a US coordinate: BLM ownership, jurisdiction, allowed activities (rockhounding, camping), permit requirements, and special designations (ACEC, Wilderness, WSA, NM/NCA).\n\nCosts **1 credit** per successful call.", "tags": [ "Endpoints" ], "x-mcp-tool": "blm_land_lookup", "x-credit-cost": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number", "description": "Latitude, -90 to 90." }, "lon": { "type": "number", "description": "Longitude, -180 to 180." }, "radius_km": { "type": "number", "description": "Optional buffer radius in km (0-50, default 1.0)." } } } } } }, "responses": { "200": { "description": "Success.", "headers": { "retry-after": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Calls permitted in the current window." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Calls left in the current window." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix time at which the window resets." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_blm_land", "jurisdiction", "allowed_activities", "permit_requirements", "special_designations", "data_as_of", "cache_hit", "sources", "request_id" ], "properties": { "is_blm_land": { "type": "boolean", "description": "True when at least one BLM-administered parcel was found at the coordinate." }, "jurisdiction": { "type": [ "object", "null" ], "description": "The governing land unit. Null when no surface-management record covers the coordinate at all, in which case the activity and permit lists are empty.", "required": [ "agency", "agency_code", "dept_code", "admin_unit_name", "admin_unit_type", "state" ], "properties": { "agency": { "type": "string", "description": "Human-readable agency name.", "example": "Bureau of Land Management" }, "agency_code": { "type": [ "string", "null" ], "description": "Agency code as published by the source layer.", "example": "BLM" }, "dept_code": { "type": [ "string", "null" ], "description": "Parent department code.", "example": "DOI" }, "admin_unit_name": { "type": [ "string", "null" ], "description": "Name of the administering unit, typically the field office." }, "admin_unit_type": { "type": [ "string", "null" ], "description": "Kind of administering unit." }, "state": { "type": [ "string", "null" ], "description": "Two-letter state code of the administering unit.", "example": "UT" } } }, "allowed_activities": { "type": "array", "description": "What you may do here, from a static rule table keyed by resolved land type. Approximate - see accuracy_note.", "items": { "type": "object", "required": [ "activity", "allowed", "notes" ], "properties": { "activity": { "type": "string", "enum": [ "rockhounding", "primitive_camping", "campfire", "ohv" ], "description": "Which activity this rule covers." }, "allowed": { "oneOf": [ { "type": "boolean" }, { "type": "string", "const": "limited" } ], "description": "true, false, or the string \"limited\" when it is permitted only under conditions described in notes. Test for the string explicitly - \"limited\" is truthy in most languages." }, "notes": { "type": "string", "description": "Conditions, limits and caveats." } } } }, "permit_requirements": { "type": "array", "description": "Permits needed for particular activities on this land type. Empty when none apply.", "items": { "type": "object", "required": [ "activity", "permit_required", "permit_type", "notes" ], "properties": { "activity": { "type": "string", "description": "The activity requiring a permit.", "example": "overnight_group" }, "permit_required": { "type": "boolean", "description": "Whether a permit is mandatory." }, "permit_type": { "type": "string", "description": "Name of the permit.", "example": "Wilderness permit" }, "notes": { "type": "string", "description": "Thresholds and conditions, e.g. group size." } } } }, "special_designations": { "type": "array", "description": "Protective overlays at this location. Present only on BLM land; an overlay usually tightens the activity rules above.", "items": { "type": "object", "required": [ "type", "name", "notes" ], "properties": { "type": { "type": "string", "enum": [ "ACEC", "Wilderness", "WSA", "NM_NCA" ], "description": "Area of Critical Environmental Concern, designated Wilderness, Wilderness Study Area, or National Monument / National Conservation Area." }, "name": { "type": "string", "description": "Name of the designated area." }, "notes": { "type": "string", "description": "Standing caveat to verify current restrictions." } } } }, "blm_coverage_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Share of surface-management records in the search area that are BLM. Present only when radius_km is greater than 0, and an envelope-level approximation rather than a true geometry intersection.", "example": 66.7 }, "data_as_of": { "type": "string", "format": "date-time", "description": "When the underlying data was queried. On a cache hit this is the ORIGINAL query time, not the time of your request." }, "cache_hit": { "type": "boolean", "description": "True when served from the 30-day cache. You are charged either way." }, "accuracy_note": { "type": "string", "description": "Standing caveat that activity and permit rules are approximate. Absent only when no jurisdiction was found." }, "sources": { "type": "object", "description": "Which upstream datasets produced this answer.", "required": [ "sma", "special_designations" ], "properties": { "sma": { "type": "string", "description": "Surface management agency layer." }, "special_designations": { "type": "string", "description": "Conservation-system and ACEC layers." } } }, "request_id": { "type": "string", "description": "Identifier for this metered call." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" }, "504": { "description": "The upstream BLM ArcGIS service did not respond. Retry shortly; the credit is not refunded automatically at this status, but no data was returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "upstream_unavailable": { "value": { "error": "upstream_unavailable" } } } } } } } } }, "/v1/coverage-check": { "post": { "operationId": "coverage_check", "summary": "Scope-completeness advisor", "description": "Scope-completeness advisor. POST a brief (or requirements[]) + your stories[] and get a coverage score + the gaps (requirements no story covers), orphan stories (possible scope creep), and missing structural buckets (auth/CRUD/error-states/tests). Tells you what the scope is missing. Deterministic, no LLM.\n\nCosts **1 credit** per successful call.", "tags": [ "Endpoints" ], "x-mcp-tool": "coverage_check", "x-credit-cost": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stories" ], "properties": { "brief": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "string" } }, "stories": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "headers": { "retry-after": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Calls permitted in the current window." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Calls left in the current window." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix time at which the window resets." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "coverage_score_0_100", "covered", "gaps", "orphans", "missing_buckets", "total_requirements", "total_stories", "verdict", "request_id" ], "properties": { "coverage_score_0_100": { "type": "integer", "minimum": 0, "maximum": 100, "example": 78, "description": "Traceability is 80 percent of the score and structural buckets the remaining 20; each missing bucket costs 5 points." }, "verdict": { "type": "string", "enum": [ "PASS", "NEEDS REVISION" ], "description": "PASS requires a score of at least 85 AND zero gaps AND zero missing buckets. A single uncovered requirement blocks a pass regardless of score - a whole missing feature must not average away." }, "total_requirements": { "type": "integer", "minimum": 0, "description": "Requirements evaluated, whether supplied directly or extracted from the brief." }, "total_stories": { "type": "integer", "minimum": 0, "description": "Stories evaluated." }, "covered": { "type": "array", "description": "Requirements matched to a story, with the match evidence.", "items": { "type": "object", "required": [ "requirement", "matched_story", "score" ], "properties": { "requirement": { "type": "string", "description": "The requirement text." }, "matched_story": { "type": "string", "description": "The story that best covers it." }, "score": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.75, "description": "Fraction of the requirement token set present in the story. A requirement is considered covered at 0.5 or above." } } } }, "gaps": { "type": "array", "items": { "type": "string" }, "description": "Requirements no story covers. These are the missing work items." }, "orphans": { "type": "array", "items": { "type": "string" }, "description": "Stories that matched no requirement. Often scope creep, sometimes a requirement nobody wrote down." }, "missing_buckets": { "type": "array", "description": "Structural areas absent from the story set entirely.", "items": { "type": "string", "enum": [ "auth/account", "CRUD", "error-states", "tests" ], "description": "A whole category of work with no story mentioning it." } }, "request_id": { "type": "string", "description": "Identifier for this metered call." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/defect-triage": { "post": { "operationId": "defect_triage", "summary": "Bug-triage advisor", "description": "Bug-triage advisor. POST one bug report (or a list) and get severity (critical/high/medium/low), category, whether it has repro steps, and what info is missing (no repro / no expected-vs-actual / no environment). For a list: priority ranking + likely-duplicate clusters. Deterministic, no LLM.\n\nCosts **1 credit** per successful call.", "tags": [ "Endpoints" ], "x-mcp-tool": "defect_triage", "x-credit-cost": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "string" }, "reports": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "headers": { "retry-after": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Calls permitted in the current window." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Calls left in the current window." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix time at which the window resets." } }, "content": { "application/json": { "schema": { "description": "The shape depends on the input: a single `report` returns one triaged record under `result`, while a `reports` list returns `results` plus cross-report ranking and duplicate detection.", "oneOf": [ { "type": "object", "title": "Single report", "required": [ "result", "request_id" ], "additionalProperties": false, "properties": { "result": { "$ref": "#/components/schemas/defect_triage_triaged" }, "request_id": { "type": "string", "description": "Identifier for this metered call." } } }, { "type": "object", "title": "Batch of reports", "required": [ "results", "ranked_order", "duplicate_clusters", "request_id" ], "additionalProperties": false, "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/defect_triage_triaged" }, "description": "One record per submitted report, in submission order." }, "ranked_order": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Indices into `results`, worst first. Sorted by severity, then by category risk (security, data, crash, performance, integration, ui, docs, other), then by submission order.", "example": [ 2, 0, 1 ] }, "duplicate_clusters": { "type": "array", "description": "Groups of indices that look like the same bug, by token overlap. Only groups of two or more appear; an empty array means no suspected duplicates.", "items": { "type": "array", "minItems": 2, "items": { "type": "integer", "minimum": 0 }, "description": "Indices into `results` that cluster together." }, "example": [ [ 0, 3 ] ] }, "request_id": { "type": "string", "description": "Identifier for this metered call." } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/dependency-check": { "post": { "operationId": "dependency_check", "summary": "Dependency-manifest hygiene check", "description": "Dependency-manifest hygiene check. POST package manifests (package.json, requirements.txt, pyproject.toml, go.mod, Gemfile, composer.json, pubspec.yaml, lockfiles) or an upload_id and get findings with severity + concrete fixes: wildcard/unbounded versions, missing lockfiles, unpinned installs, non-https indexes, install-script risks, dependency-confusion signals, and matches against a static snapshot of famously compromised packages. NOT a live CVE feed - pair with npm audit / pip-audit / osv-scanner for that. Deterministic, no network, no LLM.\n\nCosts **1 credit** per successful call.", "tags": [ "Endpoints" ], "x-mcp-tool": "dependency_check", "x-credit-cost": 1, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "manifests": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content": { "type": "string" } }, "required": [ "filename", "content" ] }, "description": "Up to 20 manifest files inline." }, "upload_id": { "type": "string", "description": "Alternative: a single manifest uploaded via the uploads tool." }, "filename": { "type": "string", "description": "Required with upload_id so the manifest type can be detected." } } } } } }, "responses": { "200": { "description": "Success.", "headers": { "retry-after": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "x-ratelimit-limit": { "schema": { "type": "integer" }, "description": "Calls permitted in the current window." }, "x-ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Calls left in the current window." }, "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Unix time at which the window resets." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "findings", "score_0_100", "grade", "summary", "snapshot_as_of", "note", "request_id" ], "properties": { "score_0_100": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Starts at 100 with a weighted deduction per finding. Findings are deduplicated before scoring, so one compromised package named in several places is counted once." }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ], "description": "A at 90, B at 80, C at 70, D at 60, F below." }, "findings": { "type": "array", "description": "Problems found, most severe first, then by file, category and message so ordering is stable across runs.", "items": { "type": "object", "required": [ "file", "severity", "category", "message", "fix" ], "properties": { "file": { "type": "string", "description": "Manifest the finding came from. The literal value \"(report)\" means the finding is about the report itself rather than about your code." }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "How urgent the finding is." }, "category": { "type": "string", "enum": [ "compromised_package", "dependency_confusion", "install_scripts", "insecure_source", "unpinned_version", "unpinned_url_dep", "unpinned_git_dep", "unbounded_range", "wildcard_version", "caret_zero", "missing_lockfile", "inconsistent_hashes", "local_replace", "missing_engines", "missing_go_directive", "missing_python_requires", "missing_sdk_constraint", "spec_not_evaluated", "parse_error", "unsupported_file", "findings_truncated", "analysis_budget_exceeded" ], "description": "Stable rule identifier. The last two are report-integrity categories, not code problems: they mean the report is INCOMPLETE - findings were dropped for size, or analysis stopped early, so later manifests may not be represented at all." }, "message": { "type": "string", "maxLength": 1000, "description": "What is wrong. Values interpolated from your manifest are clipped, since manifest content is untrusted." }, "fix": { "type": "string", "maxLength": 1000, "description": "What to do about it." } } } }, "summary": { "type": "object", "required": [ "by_severity", "files_checked", "manifest_types" ], "properties": { "by_severity": { "type": "object", "description": "Finding counts per severity. All four keys are always present, including zeros.", "required": [ "critical", "high", "medium", "low" ], "additionalProperties": false, "properties": { "critical": { "type": "integer", "minimum": 0, "description": "Count of critical findings." }, "high": { "type": "integer", "minimum": 0, "description": "Count of high findings." }, "medium": { "type": "integer", "minimum": 0, "description": "Count of medium findings." }, "low": { "type": "integer", "minimum": 0, "description": "Count of low findings." } } }, "files_checked": { "type": "integer", "minimum": 0, "description": "Recognised manifests actually analysed. Unsupported files are reported as a finding and excluded from this count." }, "manifest_types": { "type": "array", "items": { "type": "string" }, "description": "Distinct manifest kinds recognised in the submission.", "example": [ "package-lock.json", "package.json" ] } } }, "snapshot_as_of": { "type": "string", "description": "Vintage of the compromised-package snapshot this scan matched against." }, "note": { "type": "string", "description": "Standing caveat that this is a static snapshot, NOT a live CVE feed. Pair it with npm audit, pip-audit or osv-scanner for current vulnerability data." }, "request_id": { "type": "string", "description": "Identifier for this metered call." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/v1/diagram-contrast": { "post": { "operationId": "diagram_contrast", "summary": "Diagram quality QA", "description": "Diagram quality QA. Catch and fix the things that ruin diagrams: (1) unreadable label contrast - POST a mermaid/SVG or HTML diagram, get every WCAG-AA failure (incl. mermaid