{
 "openapi": "3.1.0",
 "info": {
  "title": "LA4KB V3 public API",
  "version": "la4kb-v3-typed-candidate-1",
  "description": "Checks whether the evidence an agent declares supports its claim: one claim plus up to 10 evidence items in, one Ed25519-signed verdict out. Deterministic rules, explicit scope. LA4KB judges the relationship between the claim and the evidence it receives; whoever supplies a source defines its quality. Live engine build v3t-1013d7ecf712 (commit caa1b44). No authentication. Rate limit 5 requests/second per IP; body <= 64 KiB. Input guide for LLMs: https://break-la4kb.eidrax.com/llms-full.txt",
  "x-engine-build": "v3t-1013d7ecf712"
 },
 "servers": [
  {
   "url": "https://break-la4kb.eidrax.com/api/v3"
  }
 ],
 "externalDocs": {
  "description": "LLM input guide",
  "url": "https://break-la4kb.eidrax.com/llms-full.txt"
 },
 "paths": {
  "/health": {
   "get": {
    "summary": "Service health",
    "operationId": "getHealth",
    "responses": {
     "200": {
      "description": "UP, with engine_build and queue metrics",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "engine_build": {
           "type": "string"
          },
          "metrics": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "503": {
      "description": "DEGRADED: worker unreachable"
     }
    }
   }
  },
  "/api-info": {
   "get": {
    "summary": "Contract metadata and public endpoints",
    "operationId": "getApiInfo",
    "responses": {
     "200": {
      "description": "Contract metadata",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/pubkey": {
   "get": {
    "summary": "Ed25519 public key for receipt verification",
    "operationId": "getPubkey",
    "responses": {
     "200": {
      "description": "Public key",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "algorithm": {
           "type": "string",
           "enum": [
            "ed25519"
           ]
          },
          "public_key_hex": {
           "type": "string"
          },
          "engine_build": {
           "type": "string"
          },
          "payload_result_binding_version": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/challenge": {
   "post": {
    "summary": "Submit a claim with its evidence for a signed verdict",
    "operationId": "submitChallenge",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ChallengeRequest"
       },
       "example": {
        "contract_version": "la4kb-v3-typed-candidate-1",
        "scope_schema_id": "la4kb.generic.v1",
        "client_reference": "llm-guide-example",
        "claim": {
         "subject": {
          "type": "label",
          "value": "svc"
         },
         "predicate": "latency_ms",
         "operator": "LE",
         "value": 100,
         "quantifier": "UNQUANTIFIED",
         "source_id": "claim-operator-1",
         "operator_provenance": {
          "type": "operator_declared",
          "operator": "LE",
          "source_id": "claim-operator-1"
         },
         "scope": {
          "dimensions": {
           "region": {
            "type": "label",
            "value": "EU"
           }
          }
         }
        },
        "evidence_items": [
         {
          "evidence_id": "measurement-1",
          "subject": {
           "type": "label",
           "value": "svc"
          },
          "predicate": "latency_ms",
          "operator": "EQ",
          "value": 75,
          "authority_tier": "PRIMARY_SOURCE",
          "evidence_nature": "INSTANCE",
          "source_id": "report-2026-q3-table-2",
          "measurement_identity": {
           "type": "measurement_id",
           "value": "sensor-a"
          },
          "scope": {
           "dimensions": {
            "region": {
             "type": "label",
             "value": "EU"
            }
           }
          }
         }
        ]
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Queued",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "job_id": {
           "type": "string",
           "pattern": "^chk-"
          },
          "status": {
           "type": "string",
           "enum": [
            "QUEUED"
           ]
          },
          "engine_build": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "422": {
      "description": "Invalid or ambiguous input (contract error, not a verdict)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "job_id": {
           "type": "null"
          },
          "status": {
           "type": "string",
           "enum": [
            "REJECTED"
           ]
          },
          "engine_build": {
           "type": "string"
          },
          "error_code": {
           "type": "string"
          },
          "errors": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "loc": {
              "type": "array"
             },
             "msg": {
              "type": "string"
             },
             "type": {
              "type": "string"
             }
            }
           }
          },
          "error_count": {
           "type": "integer"
          },
          "hint": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate limited"
     },
     "503": {
      "description": "WORKER_UNAVAILABLE; no job created"
     }
    }
   }
  },
  "/challenge/{job_id}": {
   "get": {
    "summary": "Poll a job; returns the signed receipt when COMPLETED",
    "operationId": "getChallenge",
    "parameters": [
     {
      "name": "job_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^chk-"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Job status or signed receipt",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Receipt"
        }
       }
      }
     },
     "404": {
      "description": "Unknown job_id"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Typed": {
    "type": "object",
    "required": [
     "type"
    ],
    "properties": {
     "type": {
      "type": "string",
      "enum": [
       "label",
       "git_commit",
       "semver",
       "integer",
       "boolean",
       "measurement_id",
       "date",
       "date_interval",
       "compound"
      ]
     }
    },
    "additionalProperties": true,
    "description": "Typed value, e.g. {\"type\":\"label\",\"value\":\"svc\"}. Bare strings reject 422."
   },
   "Scope": {
    "type": "object",
    "properties": {
     "dimensions": {
      "type": "object",
      "additionalProperties": {
       "$ref": "#/components/schemas/Typed"
      }
     },
     "software_version": {
      "$ref": "#/components/schemas/Typed"
     },
     "document_revision": {
      "$ref": "#/components/schemas/Typed"
     },
     "measurement_window": {
      "$ref": "#/components/schemas/Typed"
     },
     "commit": {
      "$ref": "#/components/schemas/Typed"
     },
     "build_number": {
      "$ref": "#/components/schemas/Typed"
     },
     "release_label": {
      "$ref": "#/components/schemas/Typed"
     }
    }
   },
   "Operator": {
    "type": "string",
    "enum": [
     "EQ",
     "NE",
     "LT",
     "LE",
     "GT",
     "GE",
     "RANGE"
    ]
   },
   "Claim": {
    "type": "object",
    "additionalProperties": false,
    "required": [
     "subject",
     "predicate",
     "operator",
     "source_id",
     "operator_provenance"
    ],
    "properties": {
     "subject": {
      "$ref": "#/components/schemas/Typed"
     },
     "predicate": {
      "type": "string"
     },
     "operator": {
      "$ref": "#/components/schemas/Operator"
     },
     "value": {
      "type": "number"
     },
     "range_bounds": {
      "type": "array",
      "minItems": 4,
      "maxItems": 4
     },
     "quantifier": {
      "type": "string",
      "enum": [
       "UNIVERSAL",
       "EXISTENTIAL",
       "STATISTICAL",
       "UNQUANTIFIED"
      ]
     },
     "source_id": {
      "type": "string",
      "description": "Required by the schema. ASCII [A-Za-z0-9][A-Za-z0-9._-]{0,127}; must equal operator_provenance.source_id.",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
     },
     "operator_provenance": {
      "type": "object",
      "required": [
       "type",
       "operator",
       "source_id"
      ],
      "properties": {
       "type": {
        "const": "operator_declared"
       },
       "operator": {
        "type": "string"
       },
       "source_id": {
        "type": "string"
       }
      }
     },
     "scope": {
      "$ref": "#/components/schemas/Scope"
     },
     "raw_text": {
      "type": "string"
     }
    }
   },
   "Evidence": {
    "type": "object",
    "additionalProperties": false,
    "required": [
     "evidence_id",
     "subject",
     "predicate",
     "authority_tier",
     "evidence_nature"
    ],
    "properties": {
     "evidence_id": {
      "type": "string"
     },
     "subject": {
      "$ref": "#/components/schemas/Typed"
     },
     "predicate": {
      "type": "string"
     },
     "operator": {
      "$ref": "#/components/schemas/Operator"
     },
     "value": {
      "type": "number"
     },
     "range_bounds": {
      "type": "array",
      "minItems": 4,
      "maxItems": 4
     },
     "uncertainty": {
      "type": "number"
     },
     "authority_tier": {
      "type": "string",
      "enum": [
       "PRIMARY_SOURCE",
       "EXTERNAL_STANDARD",
       "OFFICIAL_VENDOR",
       "INDEPENDENT_BENCHMARK",
       "CANDIDATE_EXTRACTOR",
       "UNVERIFIED"
      ]
     },
     "evidence_nature": {
      "type": "string",
      "enum": [
       "INSTANCE",
       "STATISTIC_AGGREGATE",
       "THEORETICAL_BOUND",
       "CONSTRAINT"
      ]
     },
     "source_id": {
      "type": "string",
      "description": "Optional in the schema; recommended for traceability (exact table, page or line)."
     },
     "measurement_identity": {
      "$ref": "#/components/schemas/Typed"
     },
     "scope": {
      "$ref": "#/components/schemas/Scope"
     }
    }
   },
   "ChallengeRequest": {
    "type": "object",
    "additionalProperties": false,
    "required": [
     "contract_version",
     "scope_schema_id",
     "claim"
    ],
    "properties": {
     "contract_version": {
      "const": "la4kb-v3-typed-candidate-1"
     },
     "scope_schema_id": {
      "type": "string",
      "enum": [
       "la4kb.generic.v1",
       "la4kb.git-deployment.v1"
      ]
     },
     "client_reference": {
      "type": "string"
     },
     "claim": {
      "$ref": "#/components/schemas/Claim"
     },
     "evidence_items": {
      "type": "array",
      "maxItems": 10,
      "items": {
       "$ref": "#/components/schemas/Evidence"
      }
     },
     "provenance": {
      "type": "object"
     },
     "origin_category": {
      "type": "string"
     },
     "researcher_attribution": {
      "type": "string"
     }
    }
   },
   "Receipt": {
    "type": "object",
    "properties": {
     "job_id": {
      "type": "string"
     },
     "status": {
      "type": "string"
     },
     "verdict": {
      "type": "string"
     },
     "engine_build": {
      "type": "string"
     },
     "client_reference": {
      "type": [
       "string",
       "null"
      ]
     },
     "payload_hash": {
      "type": "string"
     },
     "result_hash": {
      "type": "string"
     },
     "signature": {
      "type": "string",
      "description": "ed25519:<hex> over engine_build:job_id:result_hash"
     },
     "binding_signature": {
      "type": "string"
     }
    }
   }
  }
 }
}