1cc453c97b
- Add PolicySourceStore for tracking where policies come from - Implement claim extraction skill and API endpoints - Add community UI text selection extractor component - Create Go SDK aphoria client for policy operations - Document patent specifications and legal disclosures - Add guides: golden path loop, policy audit trails, pre-flight checks - Expand Unreal Engine config extractor with source tracking - Add UAT reports for policy source tracking validation - Refactor tests.rs into modular test files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
4995 lines
157 KiB
JSON
4995 lines
157 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Episteme (StemeDB) API",
|
|
"description": "HTTP API for the probabilistic knowledge graph",
|
|
"contact": {
|
|
"name": "Episteme Project"
|
|
},
|
|
"license": {
|
|
"name": ""
|
|
},
|
|
"version": "0.1.0"
|
|
},
|
|
"paths": {
|
|
"/v1/admin/circuit-breaker/reset": {
|
|
"post": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "POST /v1/admin/circuit-breaker/reset",
|
|
"description": "Manually reset a circuit breaker (admin operation).",
|
|
"operationId": "reset_circuit",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ResetCircuitRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Circuit breaker reset successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ResetCircuitResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid agent ID format",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/circuit-breaker/{agent_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "GET /v1/admin/circuit-breaker/{agent_id}",
|
|
"description": "Get the circuit breaker status for a specific agent.",
|
|
"operationId": "get_circuit_status",
|
|
"parameters": [
|
|
{
|
|
"name": "agent_id",
|
|
"in": "path",
|
|
"description": "Hex-encoded agent ID (64 characters)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Circuit breaker status retrieved",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CircuitBreakerStatusResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid agent ID format",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/circuit-breakers/tripped": {
|
|
"get": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "GET /v1/admin/circuit-breakers/tripped",
|
|
"description": "List all tripped (Open or HalfOpen) circuit breakers.",
|
|
"operationId": "list_tripped_circuits",
|
|
"parameters": [
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Maximum number of circuits to return (default: 100)",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Tripped circuits retrieved",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/TrippedCircuitsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/decay-trust-ranks": {
|
|
"post": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "Apply confidence half-life decay to all stored TrustRanks.",
|
|
"description": "This is an admin operation that should be run periodically (e.g., daily)\nby The Gardener. Agents who haven't been active will see their trust\nscores gradually regress toward the mean.",
|
|
"operationId": "decay_trust_ranks",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DecayTrustRanksRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Decay operation completed",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DecayTrustRanksResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/escalations": {
|
|
"get": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "GET /v1/admin/escalations",
|
|
"description": "List all pending escalation events, or all escalations since a timestamp.",
|
|
"operationId": "list_escalations",
|
|
"parameters": [
|
|
{
|
|
"name": "since",
|
|
"in": "query",
|
|
"description": "Only return escalations since this timestamp (nanoseconds)",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Escalations retrieved successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/EscalationListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/escalations/{id}/resolve": {
|
|
"post": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "POST /v1/admin/escalations/{id}/resolve",
|
|
"description": "Mark an escalation event as resolved.",
|
|
"operationId": "resolve_escalation",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"description": "Hex-encoded escalation event ID",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Escalation resolved successfully"
|
|
},
|
|
"400": {
|
|
"description": "Invalid escalation ID",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Escalation not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/gold-standards": {
|
|
"get": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "List all gold standards.",
|
|
"operationId": "list_gold_standards",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Gold standards retrieved",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GoldStandardListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "Create a new gold standard.",
|
|
"description": "Only administrators should have access to this endpoint. The gold standard\nreferences an existing assertion that has been verified as ground truth.",
|
|
"operationId": "create_gold_standard",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateGoldStandardRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Gold standard created",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateGoldStandardResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/gold-standards/{subject}/{predicate}": {
|
|
"delete": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "Remove a gold standard.",
|
|
"operationId": "remove_gold_standard",
|
|
"parameters": [
|
|
{
|
|
"name": "subject",
|
|
"in": "path",
|
|
"description": "Subject entity",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "predicate",
|
|
"in": "path",
|
|
"description": "Predicate",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Gold standard removed or not found"
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/quarantine": {
|
|
"get": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "GET /v1/admin/quarantine",
|
|
"description": "List pending quarantine events (or all events if include_reviewed=true).",
|
|
"operationId": "list_quarantine",
|
|
"parameters": [
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Maximum number of events to return (default: 100)",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0
|
|
}
|
|
},
|
|
{
|
|
"name": "include_reviewed",
|
|
"in": "query",
|
|
"description": "Include reviewed events (default: false)",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Quarantine events retrieved successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/QuarantineListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/quarantine/{hash}": {
|
|
"get": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "GET /v1/admin/quarantine/{hash}",
|
|
"description": "Get a specific quarantine event by hash (includes assertion bytes).",
|
|
"operationId": "get_quarantine",
|
|
"parameters": [
|
|
{
|
|
"name": "hash",
|
|
"in": "path",
|
|
"description": "Hex-encoded hash of the quarantined assertion",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Quarantine event retrieved successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/QuarantineGetResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid hash format",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Quarantine event not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/quarantine/{hash}/approve": {
|
|
"post": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "POST /v1/admin/quarantine/{hash}/approve",
|
|
"description": "Approve a quarantined assertion, returning the assertion bytes for indexing.",
|
|
"operationId": "approve_quarantine",
|
|
"parameters": [
|
|
{
|
|
"name": "hash",
|
|
"in": "path",
|
|
"description": "Hex-encoded hash of the quarantined assertion",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Quarantine event approved successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/QuarantineApproveResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid hash format",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Quarantine event not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/quarantine/{hash}/reject": {
|
|
"post": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "POST /v1/admin/quarantine/{hash}/reject",
|
|
"description": "Reject a quarantined assertion (remains in quarantine for audit trail).",
|
|
"operationId": "reject_quarantine",
|
|
"parameters": [
|
|
{
|
|
"name": "hash",
|
|
"in": "path",
|
|
"description": "Hex-encoded hash of the quarantined assertion",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Quarantine event rejected successfully"
|
|
},
|
|
"400": {
|
|
"description": "Invalid hash format",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Quarantine event not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admin/verify-agent": {
|
|
"post": {
|
|
"tags": [
|
|
"admin"
|
|
],
|
|
"summary": "Verify an agent against a gold standard.",
|
|
"description": "This endpoint checks if the agent's answer matches the gold standard's\nexpected object. The agent's TrustRank is updated accordingly:\n- Correct answer: +0.05 trust\n- Incorrect answer: -0.1 trust",
|
|
"operationId": "verify_agent",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/VerifyAgentRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Agent verified",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/VerificationResult"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Gold standard not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"409": {
|
|
"description": "Agent already verified this gold standard",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/admission/status": {
|
|
"get": {
|
|
"tags": [
|
|
"admission"
|
|
],
|
|
"summary": "Get admission status for an agent.",
|
|
"description": "Returns the agent's current admission status including trust tier,\nPoW requirements, and quota multipliers based on their reputation\nscore and assertion count.\n\n# Response Headers\n\nWhen admission middleware is enabled, responses also include:\n- `X-Trust-Tier`: Agent's trust tier name\n- `X-PoW-Required`: \"true\" or \"false\"\n- `X-PoW-Difficulty`: Required difficulty in bits\n- `X-Quota-Multiplier`: Tier quota multiplier\n\n# Graduation Milestones\n\nThe response includes how many more assertions are needed to reach\nreduced difficulty (10 assertions) or exemption (50 assertions).",
|
|
"operationId": "get_admission_status",
|
|
"parameters": [
|
|
{
|
|
"name": "agent_id",
|
|
"in": "query",
|
|
"description": "Agent's Ed25519 public key (hex-encoded, 64 chars)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Admission status retrieved",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AdmissionStatusResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid agent_id format"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/assert": {
|
|
"post": {
|
|
"tags": [
|
|
"assertions"
|
|
],
|
|
"summary": "Create a new assertion in the knowledge graph.",
|
|
"description": "This endpoint accepts an assertion DTO, validates confidence bounds (0.0-1.0),\nconverts hex-encoded fields to binary, serializes the assertion to WAL format,\nand appends it to the journal. Returns the content-addressed BLAKE3 hash.\n\n# Validation\n- Confidence must be between 0.0 and 1.0\n- At least one signature is required\n- All hex fields must have correct lengths (32 bytes for hashes, 64 bytes for signatures)",
|
|
"operationId": "create_assertion",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateAssertionRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Assertion created successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/audit/queries": {
|
|
"get": {
|
|
"tags": [
|
|
"audit"
|
|
],
|
|
"summary": "List recent query audits with optional filters.",
|
|
"description": "Returns a paginated list of query audit records. Use the `agent_id` and\ntime range filters to narrow down results for incident investigation.\n\n# Query Parameters\n\n- `agent_id` (optional): Filter by agent public key (hex-encoded, 32 bytes)\n- `from` (optional): Start of time range (Unix timestamp)\n- `to` (optional): End of time range (Unix timestamp)\n- `limit` (optional): Maximum number of results (default: 100)",
|
|
"operationId": "list_audits",
|
|
"parameters": [
|
|
{
|
|
"name": "agent_id",
|
|
"in": "path",
|
|
"description": "Filter by agent public key (hex-encoded, 32 bytes)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"name": "from",
|
|
"in": "path",
|
|
"description": "Start of time range (Unix timestamp)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"minimum": 0
|
|
}
|
|
},
|
|
{
|
|
"name": "to",
|
|
"in": "path",
|
|
"description": "End of time range (Unix timestamp)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"minimum": 0
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "path",
|
|
"description": "Maximum number of results to return (defaults to 100)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of query audits",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/QueryAuditListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/audit/query/{id}": {
|
|
"get": {
|
|
"tags": [
|
|
"audit"
|
|
],
|
|
"summary": "Get a specific query audit by ID.",
|
|
"description": "Returns the full audit record including all contributing assertions\nthat influenced the query result.",
|
|
"operationId": "get_audit",
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"description": "Query ID (hex-encoded, 32 bytes)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Query audit details",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/QueryAuditResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid query ID",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Audit not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/concepts/alias": {
|
|
"post": {
|
|
"tags": [
|
|
"concepts"
|
|
],
|
|
"summary": "Create a new concept alias.",
|
|
"description": "Creates a bidirectional mapping between an alias path and its canonical form.\nThis enables cross-scheme entity resolution in queries.\n\n# Example\n\n```json\n{\n \"alias_path\": \"code://rust/auth/jwt/aud\",\n \"canonical_path\": \"rfc://7519/jwt/audience_validation\",\n \"agent_id\": \"deadbeef...\"\n}\n```",
|
|
"operationId": "create_alias",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateAliasRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Alias created",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AliasResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"concepts"
|
|
],
|
|
"summary": "Delete a concept alias.",
|
|
"description": "Removes the alias and updates the reverse index.",
|
|
"operationId": "delete_alias",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeleteAliasRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Alias deleted",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeleteAliasResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/concepts/aliases": {
|
|
"get": {
|
|
"tags": [
|
|
"concepts"
|
|
],
|
|
"summary": "List all aliases, optionally filtered by canonical path.",
|
|
"operationId": "list_aliases",
|
|
"parameters": [
|
|
{
|
|
"name": "canonical_path",
|
|
"in": "query",
|
|
"description": "Filter by canonical path",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Max results (default: 100)",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of aliases",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ListAliasesResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/concepts/parse": {
|
|
"get": {
|
|
"tags": [
|
|
"concepts"
|
|
],
|
|
"summary": "Parse a path and return ConceptPath information.",
|
|
"description": "Returns scheme, segments, leaf, and inferred source class.",
|
|
"operationId": "parse_concept_path",
|
|
"parameters": [
|
|
{
|
|
"name": "path",
|
|
"in": "query",
|
|
"description": "Path to parse",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Parsed concept path",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConceptPathInfo"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid path",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/concepts/resolve": {
|
|
"get": {
|
|
"tags": [
|
|
"concepts"
|
|
],
|
|
"summary": "Resolve a path to its canonical and/or all related paths.",
|
|
"description": "If `transitive=true`, returns all paths reachable through the alias graph\n(including cycles, which are handled safely).",
|
|
"operationId": "resolve_alias",
|
|
"parameters": [
|
|
{
|
|
"name": "path",
|
|
"in": "query",
|
|
"description": "Path to resolve",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "transitive",
|
|
"in": "query",
|
|
"description": "Resolve transitively (default: false)",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Resolved paths",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ResolveAliasResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/concepts/suggest": {
|
|
"get": {
|
|
"tags": [
|
|
"concepts"
|
|
],
|
|
"summary": "Suggest aliases for a path based on existing subjects.",
|
|
"description": "Finds existing subjects with similar leaf names across different schemes.",
|
|
"operationId": "suggest_aliases",
|
|
"parameters": [
|
|
{
|
|
"name": "path",
|
|
"in": "query",
|
|
"description": "Path to get suggestions for",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Alias suggestions",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SuggestAliasesResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/constraints": {
|
|
"get": {
|
|
"tags": [
|
|
"query"
|
|
],
|
|
"summary": "Query for constraint analysis using ConstraintsLens.",
|
|
"description": "This endpoint provides pre-flight constraint checking for AI agents,\ncategorizing assertions by predicate pattern into must_use, forbidden, and prefer.\n\n# Predicate Patterns\n\n- `must_use:*` → Required, non-negotiable constraints\n- `forbidden:*` → Explicitly banned items\n- `prefer:*` → Recommended but optional\n\n# Response\n\nReturns a `ConstraintsResponse` with:\n- `must_use`: Required constraints sorted by confidence\n- `forbidden`: Banned items sorted by confidence\n- `prefer`: Recommendations sorted by confidence\n\n# Example\n\n```ignore\nGET /v1/constraints?subject=project_alpha\n\n{\n \"subject\": \"project_alpha\",\n \"must_use\": [\n { \"category\": \"http_client\", \"value\": {\"type\": \"Text\", \"value\": \"axios\"}, \"confidence\": 0.95 }\n ],\n \"forbidden\": [\n { \"category\": \"http_client\", \"value\": {\"type\": \"Text\", \"value\": \"requests\"}, \"confidence\": 0.9 }\n ],\n \"prefer\": [\n { \"category\": \"language\", \"value\": {\"type\": \"Text\", \"value\": \"typescript\"}, \"confidence\": 0.8 }\n ]\n}\n```",
|
|
"operationId": "constraints_query",
|
|
"parameters": [
|
|
{
|
|
"name": "subject",
|
|
"in": "path",
|
|
"description": "Subject entity to check constraints for (required)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Constraint analysis successful",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConstraintsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/epoch": {
|
|
"post": {
|
|
"tags": [
|
|
"epochs"
|
|
],
|
|
"summary": "Create a new epoch (paradigm) in the knowledge graph.",
|
|
"description": "Epochs represent distinct periods of truth or worldviews. Assertions can\nreference epochs to indicate which paradigm they belong to. Epochs can\nsupersede previous epochs via Invalidation, Temporal, or Refinement.\n\n# Epoch ID Generation\n\nThe epoch ID is computed as BLAKE3 hash of a canonical string representation:\n`\"{name}:{supersedes_hex}:{timestamp}\"`. This ensures:\n- Deterministic IDs for the same input (same name + timestamp = same ID)\n- IDs that won't change if the Epoch struct's serialization format changes\n- Human-readable debugging via the canonical format\n\n# Validation\n\n- Name must be non-empty\n- Supersedes field, if provided, must be a valid 32-byte hex-encoded hash\n- If supersedes is provided, supersession_type is required\n\n# Example Request (New Epoch)\n\n```json\n{\n \"name\": \"GAAP-2024\",\n \"start_timestamp\": 1704067200\n}\n```\n\n# Example Request (Superseding an Epoch)\n\nUse this same endpoint to supersede a previous epoch by providing the\n`supersedes` field with the hex-encoded ID of the epoch being replaced:\n\n```json\n{\n \"name\": \"post_fda_label_2024\",\n \"supersedes\": \"a1b2c3d4e5f6...64-hex-chars...\",\n \"supersession_type\": \"Invalidate\"\n}\n```\n\n## Supersession Types\n\n- **Invalidate**: Previous epoch was factually incorrect (e.g., FDA withdraws approval)\n- **Temporal**: Previous epoch was correct at the time but is now outdated (e.g., label update)\n- **Refinement**: Previous epoch was a simplification; new one is more precise\n- **RequiresReview**: Flagged for human review before resolution\n- **Additive**: New epoch adds to (doesn't replace) the previous one",
|
|
"operationId": "create_epoch",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateEpochRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Epoch created successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/health": {
|
|
"get": {
|
|
"tags": [
|
|
"health"
|
|
],
|
|
"summary": "Health check endpoint.",
|
|
"description": "Returns service status (\"healthy\"), API version, and the total number of assertions\ncurrently stored in the database. Useful for monitoring and load balancer health checks.",
|
|
"operationId": "health_check",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Service is healthy",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HealthResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/layered": {
|
|
"get": {
|
|
"tags": [
|
|
"query"
|
|
],
|
|
"summary": "Query for per-tier consensus using LayeredConsensusLens.",
|
|
"description": "This endpoint provides visibility into what each source class tier says,\nenabling \"What does Tier 0 (FDA) say? What does Tier 5 (Reddit) say?\" queries.\n\n# Response\n\nReturns a `LayeredQueryResponse` with:\n- `tiers`: Per-tier consensus results (only tiers with candidates)\n- `overall_winner`: Winner from the highest-authority tier present\n- `overall_conflict_score`: Cross-tier disagreement (0.0 = tiers agree, 1.0 = tiers disagree)\n\n# Example\n\n```ignore\nGET /v1/layered?subject=Semaglutide&predicate=muscle_effect\n\n{\n \"subject\": \"Semaglutide\",\n \"predicate\": \"muscle_effect\",\n \"tiers\": [\n {\n \"tier\": 1,\n \"source_class\": \"Clinical\",\n \"winner\": { ... },\n \"candidates_count\": 12,\n \"conflict_score\": 0.15,\n \"resolution_confidence\": 0.85\n },\n {\n \"tier\": 5,\n \"source_class\": \"Anecdotal\",\n \"winner\": { ... },\n \"candidates_count\": 200,\n \"conflict_score\": 0.45,\n \"resolution_confidence\": 0.55\n }\n ],\n \"overall_winner\": { ... },\n \"overall_conflict_score\": 0.78,\n \"total_candidates\": 212,\n \"lens_name\": \"LayeredConsensus\"\n}\n```",
|
|
"operationId": "layered_query",
|
|
"parameters": [
|
|
{
|
|
"name": "subject",
|
|
"in": "path",
|
|
"description": "Subject entity to analyze (required)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "predicate",
|
|
"in": "path",
|
|
"description": "Predicate/relation to analyze (required)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "include_source_metadata",
|
|
"in": "path",
|
|
"description": "Include human-readable source metadata in the response.\nWhen true, each source will include label, tier, tier_label, and url.",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Layered consensus successful",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/LayeredQueryResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "No assertions found for subject+predicate",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/meter/quota": {
|
|
"get": {
|
|
"tags": [
|
|
"meter"
|
|
],
|
|
"summary": "Get quota status for an agent.",
|
|
"description": "Returns the current quota status including remaining tokens,\nlimit, and reset time for the current hourly window.",
|
|
"operationId": "get_quota_status",
|
|
"parameters": [
|
|
{
|
|
"name": "agent_id",
|
|
"in": "query",
|
|
"description": "Agent's Ed25519 public key (hex-encoded, 64 chars)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Quota status retrieved",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/QuotaStatusResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid agent_id format"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/meter/quota/limit": {
|
|
"post": {
|
|
"tags": [
|
|
"meter"
|
|
],
|
|
"summary": "Set a custom quota limit for an agent.",
|
|
"operationId": "set_quota_limit",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SetQuotaLimitRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Quota limit updated",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SetQuotaLimitResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/provenance/{hash}": {
|
|
"get": {
|
|
"tags": [
|
|
"provenance"
|
|
],
|
|
"summary": "Retrieve a source document by its hash.",
|
|
"description": "Looks up the source at `SRC:{hash}` and returns the content with metadata.\nReturns 404 if the source hash is not found.",
|
|
"operationId": "get_provenance",
|
|
"parameters": [
|
|
{
|
|
"name": "hash",
|
|
"in": "path",
|
|
"description": "BLAKE3 hash of the source document (hex-encoded, 64 chars)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Source document found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ProvenanceResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid hash format",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Source not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/query": {
|
|
"get": {
|
|
"tags": [
|
|
"query"
|
|
],
|
|
"summary": "Query assertions with optional filters and lens-based conflict resolution.",
|
|
"description": "This endpoint builds a query from parameters (subject, predicate, lifecycle, epoch, limit),\nexecutes it via the QueryEngine, optionally applies a Lens for conflict resolution,\nand returns matching assertions. Returns early with empty results if no assertions match.\n\n# Lens Resolution\nWhen a lens is specified, it resolves conflicts among matching assertions and returns\nonly the winning assertion based on the lens strategy (Recency, Consensus, Authority, etc.)\n\n# Audit Trail\nEvery query is logged to the audit trail for incident investigation.\nInclude the `X-Agent-Id` header (hex-encoded, 32 bytes) to associate queries with an agent.",
|
|
"operationId": "query_assertions",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Query successful",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/QueryResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/skeptic": {
|
|
"get": {
|
|
"tags": [
|
|
"query"
|
|
],
|
|
"summary": "Query for conflict analysis using SkepticLens.",
|
|
"description": "This endpoint provides \"Trust but Verify\" analysis, showing all competing\nclaims for a subject+predicate instead of picking a single winner.\n\n# Response\n\nReturns a `SkepticResponse` with:\n- `status`: Unanimous, Agreed, or Contested\n- `conflict_score`: 0.0 (unanimous) to 1.0 (chaos)\n- `claims`: All distinct claims ranked by support\n\n# Example\n\n```ignore\nGET /v1/skeptic?subject=Semaglutide&predicate=muscle_effect\n\n{\n \"status\": \"Contested\",\n \"conflict_score\": 0.72,\n \"claims\": [\n { \"value\": {\"type\": \"Text\", \"value\": \"Significant loss\"}, \"weight_share\": 0.45 },\n { \"value\": {\"type\": \"Text\", \"value\": \"Minimal loss\"}, \"weight_share\": 0.35 }\n ]\n}\n```",
|
|
"operationId": "skeptic_query",
|
|
"parameters": [
|
|
{
|
|
"name": "subject",
|
|
"in": "path",
|
|
"description": "Subject entity to analyze (required)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "predicate",
|
|
"in": "path",
|
|
"description": "Predicate/relation to analyze (required)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "include_source_metadata",
|
|
"in": "path",
|
|
"description": "Include human-readable source metadata in the response.\nWhen true, each source will include label, tier, tier_label, and url.",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Conflict analysis successful",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SkepticResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "No assertions found for subject+predicate",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/source": {
|
|
"post": {
|
|
"tags": [
|
|
"provenance"
|
|
],
|
|
"summary": "Store a source document by content hash.",
|
|
"description": "Computes the BLAKE3 hash of the content and stores at `SRC:{hash}`.\nThe same content always produces the same hash (content-addressed).\nRe-uploading the same content is idempotent - no error, same hash returned.",
|
|
"operationId": "store_source",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/StoreSourceRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Source stored successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/StoreSourceResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request (bad base64, too large)",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/supersede": {
|
|
"post": {
|
|
"tags": [
|
|
"supersession"
|
|
],
|
|
"summary": "Create a supersession record for error correction.",
|
|
"description": "This endpoint accepts a supersession request, validates the fields,\nand stores the supersession record. Future queries will automatically\nfilter out superseded assertions based on type.\n\n# Request Body\n\n- `target_hash`: Hash of the assertion being superseded (hex-encoded)\n- `supersession_type`: How the target is being superseded (Invalidate, Temporal, etc.)\n- `reason`: Human-readable explanation for audit trail\n- `new_hash`: Hash of replacement assertion (optional)\n- `agent_id`: Public key of agent creating the supersession\n- `signature`: Signature over the supersession content\n\n# Example\n\n```text\nPOST /v1/supersede\n{\n \"target_hash\": \"abc123...\",\n \"supersession_type\": \"Invalidate\",\n \"reason\": \"Proposal treated as approved. See incident INC-2024-001\",\n \"new_hash\": \"def456...\",\n \"agent_id\": \"deadbeef...\",\n \"signature\": \"...\"\n}\n```",
|
|
"operationId": "supersede",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SupersedeRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Supersession recorded successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SupersedeResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Target assertion not found",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"409": {
|
|
"description": "Assertion already superseded",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/trace": {
|
|
"get": {
|
|
"tags": [
|
|
"audit"
|
|
],
|
|
"summary": "Query the audit log for agent decision tracing.",
|
|
"description": "Returns query audits for a specific agent within a time range, optionally\nfiltered by subject pattern. This enables \"Why did the agent think that?\"\ndebugging for incident investigation.\n\n# Query Parameters\n\n- `agent_id` (required): Agent public key (hex-encoded, 32 bytes)\n- `from` (required): Start of time range (Unix timestamp)\n- `to` (optional): End of time range (Unix timestamp, defaults to now)\n- `subject` (optional): Filter by subject pattern (e.g., \"Tesla*\", \"auth/*\", \"*\" for all)\n- `limit` (optional): Maximum number of results (default: 100, max: 1000)\n\n# Example\n\n```text\nGET /v1/trace?agent_id=deadbeef...&from=1704067200&to=1704153600&subject=Tesla*&limit=50\n```",
|
|
"operationId": "trace",
|
|
"parameters": [
|
|
{
|
|
"name": "agent_id",
|
|
"in": "path",
|
|
"description": "Filter by agent public key (hex-encoded, 32 bytes) - required",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "from",
|
|
"in": "path",
|
|
"description": "Start of time range (Unix timestamp or ISO8601) - required",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "to",
|
|
"in": "path",
|
|
"description": "End of time range (Unix timestamp or ISO8601, defaults to now)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"name": "subject",
|
|
"in": "path",
|
|
"description": "Filter by subject pattern (e.g., \"Tesla*\", \"auth/*\")",
|
|
"required": true,
|
|
"schema": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "path",
|
|
"description": "Maximum number of results (default: 100)",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Matching query audits for the agent",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/TraceResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/vote": {
|
|
"post": {
|
|
"tags": [
|
|
"votes"
|
|
],
|
|
"summary": "Create a new vote on an assertion.",
|
|
"description": "This endpoint accepts a vote DTO, validates weight bounds (0.0-1.0),\nconverts hex-encoded fields to binary, serializes the vote to WAL format,\nand appends it to the journal. Returns the content-addressed BLAKE3 hash.\n\n# Validation\n- Weight must be between 0.0 and 1.0\n- All hex fields must have correct lengths (32 bytes for agent_id/assertion_hash, 64 bytes for signature)",
|
|
"operationId": "create_vote",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateVoteRequest"
|
|
}
|
|
}
|
|
},
|
|
"required": true
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Vote created successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid request",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"AdmissionStatusParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for admission status.",
|
|
"required": [
|
|
"agent_id"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Agent's Ed25519 public key (hex-encoded, 64 chars)"
|
|
}
|
|
}
|
|
},
|
|
"AdmissionStatusResponse": {
|
|
"type": "object",
|
|
"description": "Response for GET /v1/admission/status.\n\nContains the agent's current admission status including trust tier,\nquota multipliers, and PoW requirements.",
|
|
"required": [
|
|
"agent_id",
|
|
"tier",
|
|
"trust_score",
|
|
"assertions_count",
|
|
"pow_difficulty",
|
|
"pow_required",
|
|
"base_quota_limit",
|
|
"effective_quota_limit",
|
|
"quota_multiplier"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Agent's Ed25519 public key (hex-encoded)."
|
|
},
|
|
"assertions_count": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Total number of assertions made by this agent.",
|
|
"minimum": 0
|
|
},
|
|
"assertions_until_exemption": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Number of assertions until PoW exemption (or null if already exempt).",
|
|
"minimum": 0
|
|
},
|
|
"assertions_until_reduced_difficulty": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Number of assertions until reduced PoW difficulty (or null if not applicable).",
|
|
"minimum": 0
|
|
},
|
|
"base_quota_limit": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Base quota limit per hour (before tier multiplier).",
|
|
"minimum": 0
|
|
},
|
|
"effective_quota_limit": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Effective quota limit per hour (after tier multiplier).",
|
|
"minimum": 0
|
|
},
|
|
"pow_difficulty": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "Required PoW difficulty in bits (0 = exempt).",
|
|
"minimum": 0
|
|
},
|
|
"pow_required": {
|
|
"type": "boolean",
|
|
"description": "Whether PoW is required for this agent's next submission."
|
|
},
|
|
"quota_multiplier": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Quota multiplier for this tier."
|
|
},
|
|
"tier": {
|
|
"$ref": "#/components/schemas/TrustTierDto",
|
|
"description": "Agent's trust tier."
|
|
},
|
|
"trust_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Agent's current trust score (0.0 to 1.0)."
|
|
}
|
|
}
|
|
},
|
|
"AgentSummaryDto": {
|
|
"type": "object",
|
|
"description": "Agent summary with trust score.",
|
|
"required": [
|
|
"agent_id",
|
|
"trust_score"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Agent's public key (hex-encoded)"
|
|
},
|
|
"trust_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Trust score at query time (0.0 to 1.0)",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"AliasMapping": {
|
|
"type": "object",
|
|
"description": "A single alias mapping.",
|
|
"required": [
|
|
"alias_path",
|
|
"canonical_path"
|
|
],
|
|
"properties": {
|
|
"alias_path": {
|
|
"type": "string",
|
|
"description": "The alias path"
|
|
},
|
|
"canonical_path": {
|
|
"type": "string",
|
|
"description": "The canonical path"
|
|
}
|
|
}
|
|
},
|
|
"AliasOriginDto": {
|
|
"type": "string",
|
|
"description": "Origin of an alias.",
|
|
"enum": [
|
|
"Manual",
|
|
"Suggested",
|
|
"Merged"
|
|
]
|
|
},
|
|
"AliasResponse": {
|
|
"type": "object",
|
|
"description": "Response after creating an alias.",
|
|
"required": [
|
|
"alias_path",
|
|
"canonical_path",
|
|
"created_at",
|
|
"origin"
|
|
],
|
|
"properties": {
|
|
"alias_path": {
|
|
"type": "string",
|
|
"description": "The alias path"
|
|
},
|
|
"canonical_path": {
|
|
"type": "string",
|
|
"description": "The canonical path"
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "When the alias was created (Unix timestamp)",
|
|
"minimum": 0
|
|
},
|
|
"origin": {
|
|
"$ref": "#/components/schemas/AliasOriginDto",
|
|
"description": "Origin of the alias"
|
|
}
|
|
}
|
|
},
|
|
"AliasSuggestion": {
|
|
"type": "object",
|
|
"description": "Alias suggestion response.",
|
|
"required": [
|
|
"suggested_canonical",
|
|
"reason"
|
|
],
|
|
"properties": {
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Reason for the suggestion (e.g., \"Same leaf 'aud' across schemes\")"
|
|
},
|
|
"suggested_canonical": {
|
|
"type": "string",
|
|
"description": "The suggested canonical path"
|
|
}
|
|
}
|
|
},
|
|
"AssertionResponse": {
|
|
"type": "object",
|
|
"description": "Response containing a single assertion.",
|
|
"required": [
|
|
"hash",
|
|
"subject",
|
|
"predicate",
|
|
"object",
|
|
"source_hash",
|
|
"source_class",
|
|
"lifecycle",
|
|
"signatures",
|
|
"confidence",
|
|
"timestamp"
|
|
],
|
|
"properties": {
|
|
"confidence": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Confidence score (0.0 to 1.0)"
|
|
},
|
|
"epoch": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Epoch ID (hex-encoded, optional)"
|
|
},
|
|
"hash": {
|
|
"type": "string",
|
|
"description": "Content-addressed hash of this assertion (hex-encoded)"
|
|
},
|
|
"lifecycle": {
|
|
"$ref": "#/components/schemas/LifecycleDto",
|
|
"description": "Lifecycle stage"
|
|
},
|
|
"object": {
|
|
"$ref": "#/components/schemas/ObjectValueDto",
|
|
"description": "The object value"
|
|
},
|
|
"parent_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hash of parent assertion (hex-encoded, optional)"
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "The predicate/relation"
|
|
},
|
|
"signatures": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/SignatureDto"
|
|
},
|
|
"description": "Agent signatures"
|
|
},
|
|
"source_class": {
|
|
"$ref": "#/components/schemas/SourceClassDto",
|
|
"description": "Source authority tier"
|
|
},
|
|
"source_hash": {
|
|
"type": "string",
|
|
"description": "Hash of source evidence (hex-encoded)"
|
|
},
|
|
"source_metadata": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Structured source metadata as a JSON string (optional).\nDomain-specific schema (journal, DOI, sample_size, etc.)."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "The subject entity"
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Creation timestamp (Unix epoch)",
|
|
"minimum": 0
|
|
},
|
|
"vector": {
|
|
"type": [
|
|
"array",
|
|
"null"
|
|
],
|
|
"items": {
|
|
"type": "number",
|
|
"format": "float"
|
|
},
|
|
"description": "Semantic embedding vector (optional)"
|
|
},
|
|
"visual_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Perceptual hash for visual anchoring (hex-encoded, optional)"
|
|
}
|
|
}
|
|
},
|
|
"AuditQueryParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for listing query audits.",
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by agent public key (hex-encoded, 32 bytes)",
|
|
"default": null
|
|
},
|
|
"from": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Start of time range (Unix timestamp)",
|
|
"default": null,
|
|
"minimum": 0
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return (defaults to 100)",
|
|
"default": 100,
|
|
"minimum": 0
|
|
},
|
|
"to": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "End of time range (Unix timestamp)",
|
|
"default": null,
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"ChangeEntryDto": {
|
|
"type": "object",
|
|
"description": "A changelog entry from a \"since\" query.\n\nRepresents a single change to a materialized view's winner.",
|
|
"required": [
|
|
"timestamp",
|
|
"new_winner_hash",
|
|
"subject",
|
|
"predicate",
|
|
"lens_name"
|
|
],
|
|
"properties": {
|
|
"lens_name": {
|
|
"type": "string",
|
|
"description": "Which lens was used for resolution."
|
|
},
|
|
"new_winner_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the new winner (hex-encoded)."
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate of the changed pair."
|
|
},
|
|
"previous_winner_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hash of the previous winner (hex-encoded, None if first MV)."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject of the changed pair."
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when the change occurred.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"CircuitBreakerStatusResponse": {
|
|
"type": "object",
|
|
"description": "Circuit breaker status response.",
|
|
"required": [
|
|
"agent_id",
|
|
"state",
|
|
"state_name",
|
|
"failure_count",
|
|
"trip_count",
|
|
"failure_counts_by_type"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Hex-encoded agent ID."
|
|
},
|
|
"failure_count": {
|
|
"type": "integer",
|
|
"description": "Number of failures in the current window.",
|
|
"minimum": 0
|
|
},
|
|
"failure_counts_by_type": {
|
|
"$ref": "#/components/schemas/FailureCountsDto",
|
|
"description": "Failure counts by type."
|
|
},
|
|
"last_failure_time": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) of the most recent failure.",
|
|
"minimum": 0
|
|
},
|
|
"last_trip_time": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) when the circuit was last tripped.",
|
|
"minimum": 0
|
|
},
|
|
"recent_failures": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/FailureEventDto"
|
|
},
|
|
"description": "Recent failures within the window."
|
|
},
|
|
"retry_after_secs": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Seconds until the agent can retry (only when Open).",
|
|
"minimum": 0
|
|
},
|
|
"state": {
|
|
"$ref": "#/components/schemas/CircuitStateDto",
|
|
"description": "Current circuit state."
|
|
},
|
|
"state_name": {
|
|
"type": "string",
|
|
"description": "Human-readable state name."
|
|
},
|
|
"trip_count": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Total number of times this circuit has tripped.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"CircuitStateDto": {
|
|
"type": "string",
|
|
"description": "Circuit state (DTO).",
|
|
"enum": [
|
|
"closed",
|
|
"open",
|
|
"half_open"
|
|
]
|
|
},
|
|
"ClaimSummaryDto": {
|
|
"type": "object",
|
|
"description": "Summary of a single claim in the conflict analysis.",
|
|
"required": [
|
|
"value",
|
|
"weight_share",
|
|
"assertion_count",
|
|
"representative_hash",
|
|
"source",
|
|
"supporting_agents"
|
|
],
|
|
"properties": {
|
|
"assertion_count": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "Number of assertions making this exact claim",
|
|
"minimum": 0
|
|
},
|
|
"representative_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the representative assertion (hex-encoded)"
|
|
},
|
|
"source": {
|
|
"$ref": "#/components/schemas/SourceSummaryDto",
|
|
"description": "Source provenance"
|
|
},
|
|
"supporting_agents": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/AgentSummaryDto"
|
|
},
|
|
"description": "Agents supporting this claim"
|
|
},
|
|
"value": {
|
|
"$ref": "#/components/schemas/ObjectValueDto",
|
|
"description": "The claimed value"
|
|
},
|
|
"weight_share": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Normalized weight (0.0 to 1.0) relative to all claims",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"ConceptPathInfo": {
|
|
"type": "object",
|
|
"description": "Parsed ConceptPath information.",
|
|
"required": [
|
|
"path",
|
|
"scheme",
|
|
"segments",
|
|
"leaf",
|
|
"inferred_source_class"
|
|
],
|
|
"properties": {
|
|
"inferred_source_class": {
|
|
"type": "string",
|
|
"description": "The inferred source class based on scheme"
|
|
},
|
|
"leaf": {
|
|
"type": "string",
|
|
"description": "The leaf (last segment)"
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "The full wire format path"
|
|
},
|
|
"scheme": {
|
|
"type": "string",
|
|
"description": "The scheme (e.g., \"code\", \"rfc\", \"fda\")"
|
|
},
|
|
"segments": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "The path segments"
|
|
}
|
|
}
|
|
},
|
|
"ConstraintEntryDto": {
|
|
"type": "object",
|
|
"description": "A constraint assertion in a specific category.",
|
|
"required": [
|
|
"category",
|
|
"value",
|
|
"confidence",
|
|
"assertion_hash",
|
|
"timestamp",
|
|
"source_class"
|
|
],
|
|
"properties": {
|
|
"assertion_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the underlying assertion (hex-encoded)"
|
|
},
|
|
"category": {
|
|
"type": "string",
|
|
"description": "The constraint category (extracted from predicate, e.g., \"http_client\" from \"must_use:http_client\")"
|
|
},
|
|
"confidence": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Confidence in this constraint (0.0 to 1.0)",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
},
|
|
"source_class": {
|
|
"$ref": "#/components/schemas/SourceClassDto",
|
|
"description": "Source class of the constraint"
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "When this constraint was asserted (Unix timestamp)",
|
|
"minimum": 0
|
|
},
|
|
"value": {
|
|
"$ref": "#/components/schemas/ObjectValueDto",
|
|
"description": "The constrained value (from assertion object)"
|
|
}
|
|
}
|
|
},
|
|
"ConstraintsQueryParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for the constraints endpoint.\n\nReturns categorized constraints (must_use, forbidden, prefer) for a subject.",
|
|
"required": [
|
|
"subject"
|
|
],
|
|
"properties": {
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject entity to check constraints for (required)"
|
|
}
|
|
}
|
|
},
|
|
"ConstraintsResponse": {
|
|
"type": "object",
|
|
"description": "Response from the constraints endpoint.\n\nReturns assertions categorized by constraint type for agent pre-flight checks.",
|
|
"required": [
|
|
"subject",
|
|
"must_use",
|
|
"forbidden",
|
|
"prefer",
|
|
"candidates_count",
|
|
"conflict_score",
|
|
"computed_at"
|
|
],
|
|
"properties": {
|
|
"candidates_count": {
|
|
"type": "integer",
|
|
"description": "Total assertions considered (including non-constraint predicates)",
|
|
"minimum": 0
|
|
},
|
|
"computed_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when this was computed",
|
|
"minimum": 0
|
|
},
|
|
"conflict_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Conflict score across all constraints (0.0 = consistent, 1.0 = conflicting)",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
},
|
|
"forbidden": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ConstraintEntryDto"
|
|
},
|
|
"description": "Forbidden constraints (predicate: `forbidden:*`). Explicitly banned."
|
|
},
|
|
"must_use": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ConstraintEntryDto"
|
|
},
|
|
"description": "Required constraints (predicate: `must_use:*`). Non-negotiable."
|
|
},
|
|
"prefer": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ConstraintEntryDto"
|
|
},
|
|
"description": "Preferred constraints (predicate: `prefer:*`). Recommendations."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "The subject that was queried"
|
|
}
|
|
}
|
|
},
|
|
"ContentQualityDto": {
|
|
"type": "object",
|
|
"description": "Content quality metrics (DTO).",
|
|
"required": [
|
|
"score",
|
|
"entropy",
|
|
"structured",
|
|
"duplicate"
|
|
],
|
|
"properties": {
|
|
"duplicate": {
|
|
"type": "boolean",
|
|
"description": "Whether this assertion is a near-duplicate."
|
|
},
|
|
"entropy": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Shannon entropy of the content (bits per character)."
|
|
},
|
|
"score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Overall quality score in [0.0, 1.0]."
|
|
},
|
|
"structured": {
|
|
"type": "boolean",
|
|
"description": "Whether the content appears to be structured data."
|
|
}
|
|
}
|
|
},
|
|
"ContributingAssertionDto": {
|
|
"type": "object",
|
|
"description": "An assertion that contributed to a query result.",
|
|
"required": [
|
|
"assertion_hash",
|
|
"weight",
|
|
"source_hash",
|
|
"lifecycle"
|
|
],
|
|
"properties": {
|
|
"assertion_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the assertion (hex-encoded)"
|
|
},
|
|
"lifecycle": {
|
|
"$ref": "#/components/schemas/LifecycleDto",
|
|
"description": "Lifecycle stage of this assertion"
|
|
},
|
|
"source_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the source evidence (hex-encoded)"
|
|
},
|
|
"weight": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "How much this assertion influenced the result (0.0 to 1.0)"
|
|
}
|
|
}
|
|
},
|
|
"CreateAliasRequest": {
|
|
"type": "object",
|
|
"description": "Request to create a concept alias.\n\nCreates a bidirectional mapping between an alias path and its canonical form.",
|
|
"required": [
|
|
"alias_path",
|
|
"canonical_path",
|
|
"agent_id"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Hex-encoded Ed25519 public key of the agent creating the alias (32 bytes)."
|
|
},
|
|
"alias_path": {
|
|
"type": "string",
|
|
"description": "The alias path (e.g., `code://rust/auth/jwt/aud`)"
|
|
},
|
|
"canonical_path": {
|
|
"type": "string",
|
|
"description": "The canonical path (e.g., `rfc://7519/jwt/audience_validation`)"
|
|
},
|
|
"origin": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/AliasOriginDto",
|
|
"description": "Origin of the alias (Manual, Suggested, Merged). Defaults to Manual."
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"CreateAssertionRequest": {
|
|
"type": "object",
|
|
"description": "Request to create a new assertion.",
|
|
"required": [
|
|
"subject",
|
|
"predicate",
|
|
"object",
|
|
"confidence",
|
|
"signatures",
|
|
"source_hash"
|
|
],
|
|
"properties": {
|
|
"confidence": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Confidence score (0.0 to 1.0)",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
},
|
|
"epoch": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Epoch ID (hex-encoded, optional)"
|
|
},
|
|
"lifecycle": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/LifecycleDto",
|
|
"description": "Lifecycle stage (defaults to Proposed if not specified)"
|
|
}
|
|
]
|
|
},
|
|
"object": {
|
|
"$ref": "#/components/schemas/ObjectValueDto",
|
|
"description": "The object value"
|
|
},
|
|
"parent_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hash of parent assertion (hex-encoded, optional for forks)"
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "The predicate/relation (e.g., \"has_revenue\")"
|
|
},
|
|
"signatures": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/SignatureDto"
|
|
},
|
|
"description": "Agent signatures vouching for this assertion"
|
|
},
|
|
"source_class": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/SourceClassDto",
|
|
"description": "Source authority tier (defaults to Expert if not specified)"
|
|
}
|
|
]
|
|
},
|
|
"source_hash": {
|
|
"type": "string",
|
|
"description": "Hash of source evidence (hex-encoded)"
|
|
},
|
|
"source_metadata": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Structured source metadata as a JSON string.\nStored as bytes internally for rkyv compatibility.\nSchema is domain-specific (journal info, social metrics, etc.)."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "The subject entity (e.g., \"Tesla_Inc\")"
|
|
},
|
|
"vector": {
|
|
"type": [
|
|
"array",
|
|
"null"
|
|
],
|
|
"items": {
|
|
"type": "number",
|
|
"format": "float"
|
|
},
|
|
"description": "Semantic embedding vector (optional)"
|
|
},
|
|
"visual_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Perceptual hash for visual anchoring (hex-encoded, optional)"
|
|
}
|
|
}
|
|
},
|
|
"CreateEpochRequest": {
|
|
"type": "object",
|
|
"description": "Request to create a new epoch.",
|
|
"required": [
|
|
"name"
|
|
],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Human-readable name (e.g., \"Pre-2024\", \"Newtonian\")"
|
|
},
|
|
"start_timestamp": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Start timestamp (Unix epoch, optional - defaults to now)",
|
|
"minimum": 0
|
|
},
|
|
"supersedes": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "ID of the epoch this supersedes (hex-encoded, optional)"
|
|
},
|
|
"supersession_type": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/SupersessionTypeDto",
|
|
"description": "How this epoch supersedes the previous one (optional)"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"CreateGoldStandardRequest": {
|
|
"type": "object",
|
|
"description": "Request to create a new gold standard.",
|
|
"required": [
|
|
"assertion_hash",
|
|
"subject",
|
|
"predicate",
|
|
"expected_object",
|
|
"created_by"
|
|
],
|
|
"properties": {
|
|
"assertion_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the verified assertion (hex-encoded, 32 bytes)."
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "Administrator identifier who is creating this gold standard."
|
|
},
|
|
"expected_object": {
|
|
"type": "string",
|
|
"description": "The canonical \"correct\" answer for this subject-predicate pair."
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate/relation (e.g., \"has_shape\", \"treats_condition\")."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject entity (e.g., \"Earth\", \"Semaglutide\")."
|
|
}
|
|
}
|
|
},
|
|
"CreateGoldStandardResponse": {
|
|
"type": "object",
|
|
"description": "Response from creating a gold standard.",
|
|
"required": [
|
|
"subject",
|
|
"predicate",
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Status message."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject entity."
|
|
}
|
|
}
|
|
},
|
|
"CreateResponse": {
|
|
"type": "object",
|
|
"description": "Response from a create operation.",
|
|
"required": [
|
|
"hash",
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"hash": {
|
|
"type": "string",
|
|
"description": "Content-addressed hash of the created resource (hex-encoded)"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Status message"
|
|
}
|
|
}
|
|
},
|
|
"CreateVoteRequest": {
|
|
"type": "object",
|
|
"description": "Request to create a new vote on an assertion.",
|
|
"required": [
|
|
"assertion_hash",
|
|
"agent_id",
|
|
"weight",
|
|
"signature"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Public key of the voting agent (hex-encoded, 32 bytes)"
|
|
},
|
|
"assertion_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the assertion being voted on (hex-encoded)"
|
|
},
|
|
"observed_context": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Optional context (page snippet, etc.) as a JSON string.\nStored as bytes internally for rkyv compatibility (same pattern as Assertion's source_metadata)."
|
|
},
|
|
"signature": {
|
|
"type": "string",
|
|
"description": "Signature over the assertion hash (hex-encoded, 64 bytes)"
|
|
},
|
|
"source_url": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "The URL where the claim was observed (optional).\nEnables votes as cryptographic witnesses: \"I saw this at this URL at this time.\""
|
|
},
|
|
"weight": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Weight of the vote (0.0 to 1.0)",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"DecayTrustRanksRequest": {
|
|
"type": "object",
|
|
"description": "Request to trigger trust rank decay.",
|
|
"properties": {
|
|
"half_life_seconds": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Half-life duration in seconds for confidence decay.\nIf not provided, uses the default of 30 days (2,592,000 seconds).",
|
|
"minimum": 0
|
|
},
|
|
"now": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Unix timestamp to use as \"now\" for decay calculation.\nIf not provided, uses the current system time.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"DecayTrustRanksResponse": {
|
|
"type": "object",
|
|
"description": "Response from the decay trust ranks operation.",
|
|
"required": [
|
|
"decayed_count",
|
|
"timestamp_used",
|
|
"half_life_used",
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"decayed_count": {
|
|
"type": "integer",
|
|
"description": "Number of TrustRanks that were actually decayed (score changed).",
|
|
"minimum": 0
|
|
},
|
|
"half_life_used": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Half-life used for decay (in seconds).",
|
|
"minimum": 0
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Status message."
|
|
},
|
|
"timestamp_used": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp used for decay calculation.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"DeleteAliasRequest": {
|
|
"type": "object",
|
|
"description": "Request to delete an alias.",
|
|
"required": [
|
|
"alias_path"
|
|
],
|
|
"properties": {
|
|
"alias_path": {
|
|
"type": "string",
|
|
"description": "The alias path to delete"
|
|
}
|
|
}
|
|
},
|
|
"DeleteAliasResponse": {
|
|
"type": "object",
|
|
"description": "Response after deleting an alias.",
|
|
"required": [
|
|
"deleted",
|
|
"alias_path"
|
|
],
|
|
"properties": {
|
|
"alias_path": {
|
|
"type": "string",
|
|
"description": "The alias path that was (attempted to be) deleted"
|
|
},
|
|
"deleted": {
|
|
"type": "boolean",
|
|
"description": "Whether the alias was deleted (false if it didn't exist)"
|
|
}
|
|
}
|
|
},
|
|
"ErrorResponse": {
|
|
"type": "object",
|
|
"description": "Error response.",
|
|
"required": [
|
|
"error",
|
|
"code"
|
|
],
|
|
"properties": {
|
|
"code": {
|
|
"type": "string",
|
|
"description": "Machine-readable error code"
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message"
|
|
}
|
|
}
|
|
},
|
|
"EscalationEventDto": {
|
|
"type": "object",
|
|
"description": "Escalation event (DTO).",
|
|
"required": [
|
|
"id",
|
|
"subject",
|
|
"predicate",
|
|
"conflict_score",
|
|
"level",
|
|
"reason",
|
|
"timestamp",
|
|
"resolved"
|
|
],
|
|
"properties": {
|
|
"conflict_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "The conflict score that triggered this escalation (0.0 to 1.0)."
|
|
},
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Hex-encoded escalation ID."
|
|
},
|
|
"level": {
|
|
"$ref": "#/components/schemas/EscalationLevelDto",
|
|
"description": "Severity level assigned by the policy."
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate of the conflicting assertion pair."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Human-readable description of why this escalation was triggered."
|
|
},
|
|
"resolved": {
|
|
"type": "boolean",
|
|
"description": "Has this escalation been acknowledged/resolved?"
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject of the conflicting assertion pair."
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (nanoseconds) when this event was created.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"EscalationLevelDto": {
|
|
"type": "string",
|
|
"description": "Escalation severity level (DTO).",
|
|
"enum": [
|
|
"low",
|
|
"medium",
|
|
"high",
|
|
"critical"
|
|
]
|
|
},
|
|
"EscalationListResponse": {
|
|
"type": "object",
|
|
"description": "Response for listing escalation events.",
|
|
"required": [
|
|
"escalations",
|
|
"count"
|
|
],
|
|
"properties": {
|
|
"count": {
|
|
"type": "integer",
|
|
"description": "Total count of escalations in this response.",
|
|
"minimum": 0
|
|
},
|
|
"escalations": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/EscalationEventDto"
|
|
},
|
|
"description": "List of escalation events."
|
|
}
|
|
}
|
|
},
|
|
"FailureCountsDto": {
|
|
"type": "object",
|
|
"description": "Failure counts by type.",
|
|
"required": [
|
|
"invalid_signature",
|
|
"input_validation",
|
|
"pow_error",
|
|
"quota_exceeded",
|
|
"application_error"
|
|
],
|
|
"properties": {
|
|
"application_error": {
|
|
"type": "integer",
|
|
"description": "Number of application error failures.",
|
|
"minimum": 0
|
|
},
|
|
"input_validation": {
|
|
"type": "integer",
|
|
"description": "Number of input validation failures.",
|
|
"minimum": 0
|
|
},
|
|
"invalid_signature": {
|
|
"type": "integer",
|
|
"description": "Number of invalid signature failures.",
|
|
"minimum": 0
|
|
},
|
|
"pow_error": {
|
|
"type": "integer",
|
|
"description": "Number of PoW failures.",
|
|
"minimum": 0
|
|
},
|
|
"quota_exceeded": {
|
|
"type": "integer",
|
|
"description": "Number of quota exceeded failures.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"FailureEventDto": {
|
|
"type": "object",
|
|
"description": "A single failure event (DTO).",
|
|
"required": [
|
|
"failure_type",
|
|
"timestamp"
|
|
],
|
|
"properties": {
|
|
"failure_type": {
|
|
"$ref": "#/components/schemas/FailureTypeDto",
|
|
"description": "Type of failure."
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (seconds) when the failure occurred.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"FailureTypeDto": {
|
|
"type": "string",
|
|
"description": "Failure type (DTO).",
|
|
"enum": [
|
|
"invalid_signature",
|
|
"input_validation",
|
|
"pow_error",
|
|
"quota_exceeded",
|
|
"application_error"
|
|
]
|
|
},
|
|
"GoldStandardDto": {
|
|
"type": "object",
|
|
"description": "Gold standard data transfer object.",
|
|
"required": [
|
|
"assertion_hash",
|
|
"subject",
|
|
"predicate",
|
|
"expected_object",
|
|
"created_at",
|
|
"created_by"
|
|
],
|
|
"properties": {
|
|
"assertion_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the verified assertion (hex-encoded, 32 bytes)."
|
|
},
|
|
"created_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when created (seconds).",
|
|
"minimum": 0
|
|
},
|
|
"created_by": {
|
|
"type": "string",
|
|
"description": "Administrator who created this gold standard."
|
|
},
|
|
"expected_object": {
|
|
"type": "string",
|
|
"description": "The canonical \"correct\" answer."
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject entity."
|
|
}
|
|
}
|
|
},
|
|
"GoldStandardListResponse": {
|
|
"type": "object",
|
|
"description": "Response from listing gold standards.",
|
|
"required": [
|
|
"gold_standards",
|
|
"count"
|
|
],
|
|
"properties": {
|
|
"count": {
|
|
"type": "integer",
|
|
"description": "Total count.",
|
|
"minimum": 0
|
|
},
|
|
"gold_standards": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/GoldStandardDto"
|
|
},
|
|
"description": "All gold standards, ordered by subject and predicate."
|
|
}
|
|
}
|
|
},
|
|
"HealthResponse": {
|
|
"type": "object",
|
|
"description": "Health check response.",
|
|
"required": [
|
|
"status",
|
|
"version",
|
|
"assertions_count"
|
|
],
|
|
"properties": {
|
|
"assertions_count": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Total number of assertions in the database",
|
|
"minimum": 0
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Service status (e.g., \"healthy\")"
|
|
},
|
|
"version": {
|
|
"type": "string",
|
|
"description": "API version"
|
|
}
|
|
}
|
|
},
|
|
"LayeredQueryResponse": {
|
|
"type": "object",
|
|
"description": "Response from a LayeredConsensus query.\n\nProvides per-tier resolution results plus an overall winner.\nUse this to see \"What does Tier 0 say? What does Tier 5 say?\"",
|
|
"required": [
|
|
"subject",
|
|
"predicate",
|
|
"tiers",
|
|
"overall_conflict_score",
|
|
"total_candidates",
|
|
"computed_at",
|
|
"lens_name"
|
|
],
|
|
"properties": {
|
|
"computed_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when this view was computed.",
|
|
"minimum": 0
|
|
},
|
|
"lens_name": {
|
|
"type": "string",
|
|
"description": "Which lens was used (always \"LayeredConsensus\")."
|
|
},
|
|
"overall_conflict_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Cross-tier disagreement score (0.0 = tiers agree, 1.0 = tiers disagree).",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
},
|
|
"overall_winner": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/AssertionResponse",
|
|
"description": "Overall winner: winner from the highest-authority tier that has candidates."
|
|
}
|
|
]
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "The predicate that was queried."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "The subject that was queried."
|
|
},
|
|
"tiers": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TierResolutionDto"
|
|
},
|
|
"description": "Per-tier consensus results, ordered by tier (0 = highest authority first).\nOnly tiers with at least one candidate are included."
|
|
},
|
|
"total_candidates": {
|
|
"type": "integer",
|
|
"description": "Total candidates considered across all tiers.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"LensDto": {
|
|
"type": "string",
|
|
"description": "Lens strategy for conflict resolution.",
|
|
"enum": [
|
|
"Recency",
|
|
"Consensus",
|
|
"Confidence",
|
|
"Authority",
|
|
"VoteAwareConsensus",
|
|
"TrustAwareAuthority",
|
|
"EpochAware",
|
|
"LayeredConsensus",
|
|
"Constraints"
|
|
]
|
|
},
|
|
"LifecycleDto": {
|
|
"type": "string",
|
|
"description": "Lifecycle stage of an assertion.",
|
|
"enum": [
|
|
"Proposed",
|
|
"UnderReview",
|
|
"Approved",
|
|
"Deprecated",
|
|
"Rejected"
|
|
]
|
|
},
|
|
"ListAliasesParams": {
|
|
"type": "object",
|
|
"description": "List all aliases query parameters.",
|
|
"properties": {
|
|
"canonical_path": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by canonical path (returns aliases pointing to this canonical)"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of aliases to return",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"ListAliasesResponse": {
|
|
"type": "object",
|
|
"description": "Response listing aliases.",
|
|
"required": [
|
|
"aliases",
|
|
"total"
|
|
],
|
|
"properties": {
|
|
"aliases": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/AliasMapping"
|
|
},
|
|
"description": "List of alias mappings (alias_path → canonical_path)"
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of aliases (may be more than returned if limited)",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"ObjectValueDto": {
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"description": "Text string value",
|
|
"required": [
|
|
"value",
|
|
"type"
|
|
],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"Text"
|
|
]
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Text string value"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Numeric value (float)",
|
|
"required": [
|
|
"value",
|
|
"type"
|
|
],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"Number"
|
|
]
|
|
},
|
|
"value": {
|
|
"type": "number",
|
|
"format": "double",
|
|
"description": "Numeric value (float)"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Boolean value",
|
|
"required": [
|
|
"value",
|
|
"type"
|
|
],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"Boolean"
|
|
]
|
|
},
|
|
"value": {
|
|
"type": "boolean",
|
|
"description": "Boolean value"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Reference to another entity",
|
|
"required": [
|
|
"value",
|
|
"type"
|
|
],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"Reference"
|
|
]
|
|
},
|
|
"value": {
|
|
"type": "string",
|
|
"description": "Reference to another entity"
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"description": "Object value in an assertion."
|
|
},
|
|
"ProvenanceResponse": {
|
|
"type": "object",
|
|
"description": "Response from retrieving a source document.",
|
|
"required": [
|
|
"hash",
|
|
"content",
|
|
"content_type",
|
|
"size"
|
|
],
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "The source document content (base64-encoded)."
|
|
},
|
|
"content_type": {
|
|
"type": "string",
|
|
"description": "MIME type of the content."
|
|
},
|
|
"hash": {
|
|
"type": "string",
|
|
"description": "BLAKE3 hash of the content (hex-encoded)."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "Size of the content in bytes.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"QuarantineApproveResponse": {
|
|
"type": "object",
|
|
"description": "Response for approving a quarantine event.",
|
|
"required": [
|
|
"hash",
|
|
"message",
|
|
"assertion_bytes_hex"
|
|
],
|
|
"properties": {
|
|
"assertion_bytes_hex": {
|
|
"type": "string",
|
|
"description": "Hex-encoded assertion bytes for indexing."
|
|
},
|
|
"hash": {
|
|
"type": "string",
|
|
"description": "The approved event's hash."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Message indicating success."
|
|
}
|
|
}
|
|
},
|
|
"QuarantineEventDto": {
|
|
"type": "object",
|
|
"description": "Quarantine event (DTO).",
|
|
"required": [
|
|
"hash",
|
|
"reason",
|
|
"reason_description",
|
|
"quality",
|
|
"timestamp",
|
|
"reviewed"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hex-encoded agent ID that submitted the assertion."
|
|
},
|
|
"approved": {
|
|
"type": [
|
|
"boolean",
|
|
"null"
|
|
],
|
|
"description": "If reviewed, was it approved (true) or rejected (false)?"
|
|
},
|
|
"assertion_bytes_base64": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Base64-encoded assertion bytes (more compact than hex, ~33% smaller).\nPreferred for large assertions. Clients should check which field is present."
|
|
},
|
|
"assertion_bytes_hex": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hex-encoded assertion bytes (for consistency with other API endpoints).\nConsider using `assertion_bytes_base64` for smaller payloads."
|
|
},
|
|
"hash": {
|
|
"type": "string",
|
|
"description": "Hex-encoded hash of the quarantined assertion."
|
|
},
|
|
"quality": {
|
|
"$ref": "#/components/schemas/ContentQualityDto",
|
|
"description": "Quality metrics at the time of quarantine."
|
|
},
|
|
"reason": {
|
|
"$ref": "#/components/schemas/QuarantineReasonDto",
|
|
"description": "Why this assertion was quarantined."
|
|
},
|
|
"reason_description": {
|
|
"type": "string",
|
|
"description": "Human-readable description of the reason."
|
|
},
|
|
"reviewed": {
|
|
"type": "boolean",
|
|
"description": "Has an admin reviewed this event?"
|
|
},
|
|
"similar_to": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hex-encoded hash of similar assertion (for duplicates)."
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp (nanoseconds) when quarantined.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"QuarantineGetResponse": {
|
|
"type": "object",
|
|
"description": "Response for getting a single quarantine event.",
|
|
"required": [
|
|
"event"
|
|
],
|
|
"properties": {
|
|
"event": {
|
|
"$ref": "#/components/schemas/QuarantineEventDto",
|
|
"description": "The quarantine event."
|
|
}
|
|
}
|
|
},
|
|
"QuarantineListParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for listing quarantine events.",
|
|
"properties": {
|
|
"include_reviewed": {
|
|
"type": "boolean",
|
|
"description": "Include reviewed events (default: false, only pending)."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of events to return (default: 100).",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"QuarantineListResponse": {
|
|
"type": "object",
|
|
"description": "Response for listing quarantine events.",
|
|
"required": [
|
|
"quarantined",
|
|
"count",
|
|
"pending_count"
|
|
],
|
|
"properties": {
|
|
"count": {
|
|
"type": "integer",
|
|
"description": "Total count of events in this response.",
|
|
"minimum": 0
|
|
},
|
|
"pending_count": {
|
|
"type": "integer",
|
|
"description": "Total count of pending (unreviewed) events.",
|
|
"minimum": 0
|
|
},
|
|
"quarantined": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/QuarantineEventDto"
|
|
},
|
|
"description": "List of quarantine events."
|
|
}
|
|
}
|
|
},
|
|
"QuarantineReasonDto": {
|
|
"type": "string",
|
|
"description": "Quarantine reason (DTO).",
|
|
"enum": [
|
|
"low_quality",
|
|
"duplicate",
|
|
"untrusted_high_confidence",
|
|
"pattern_match"
|
|
]
|
|
},
|
|
"QueryAuditListResponse": {
|
|
"type": "object",
|
|
"description": "Response from listing query audits.",
|
|
"required": [
|
|
"audits",
|
|
"total_count"
|
|
],
|
|
"properties": {
|
|
"audits": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/QueryAuditResponse"
|
|
},
|
|
"description": "List of query audit records"
|
|
},
|
|
"total_count": {
|
|
"type": "integer",
|
|
"description": "Total number of results returned",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"QueryAuditResponse": {
|
|
"type": "object",
|
|
"description": "Response containing a query audit record.",
|
|
"required": [
|
|
"query_id",
|
|
"timestamp",
|
|
"params",
|
|
"result_confidence",
|
|
"contributing_assertions"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Agent public key who made the query (hex-encoded, optional)"
|
|
},
|
|
"contributing_assertions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ContributingAssertionDto"
|
|
},
|
|
"description": "Assertions that contributed to this result"
|
|
},
|
|
"params": {
|
|
"$ref": "#/components/schemas/QueryParamsAuditDto",
|
|
"description": "Query parameters that were used"
|
|
},
|
|
"query_id": {
|
|
"type": "string",
|
|
"description": "Unique identifier for this query (hex-encoded, 32 bytes)"
|
|
},
|
|
"result_confidence": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Confidence score of the resolution (0.0 to 1.0)"
|
|
},
|
|
"result_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hash of the winning assertion (hex-encoded, optional)"
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when the query was executed",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"QueryParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for searching assertions.",
|
|
"properties": {
|
|
"as_of": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Query state as of this Unix timestamp (time-travel).\n\nReturns only assertions created at or before this timestamp.\nWhen set, the fast path (MV lookup) is bypassed.\n\n- Not set: Query current state (default)\n- 0: Return assertions from the beginning of time (all timestamps >= 0)\n- 1704067200: Return assertions as of 2024-01-01 00:00:00 UTC",
|
|
"default": null,
|
|
"minimum": 0
|
|
},
|
|
"decay_halflife": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Decay half-life in seconds for confidence decay.\n\nWhen set, older assertions have their effective confidence reduced based on age.\nThis implements semantic decay: older sources shouldn't compete equally\nwith recent evidence.\n\nFormula: `effective_confidence = confidence * 2^(-(age / halflife))`\n\n- Not set: No decay (default, backward-compatible)\n- 31536000: 1-year half-life (~50% confidence loss per year)\n- 86400: 1-day half-life (fast decay for rapidly changing data)\n\n**Note**: When decay is enabled, materialized views (fast path) are bypassed\nbecause MVs store pre-computed winners without decay applied. Queries with\ndecay always use the slow path to ensure accurate confidence ordering.",
|
|
"default": null,
|
|
"minimum": 0
|
|
},
|
|
"epoch": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by epoch (hex-encoded)",
|
|
"default": null
|
|
},
|
|
"k": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"description": "Number of nearest neighbors to return for vector search.\n\nOnly used when `vector_near` is set. Defaults to 10 if not specified.\n\n- Not set: Return 10 nearest neighbors (default)\n- Set: Return up to `k` nearest neighbors",
|
|
"default": null,
|
|
"minimum": 0
|
|
},
|
|
"lens": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/LensDto",
|
|
"description": "Apply a lens for conflict resolution"
|
|
}
|
|
],
|
|
"default": null
|
|
},
|
|
"lifecycle": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/LifecycleDto",
|
|
"description": "Filter by lifecycle stage"
|
|
}
|
|
],
|
|
"default": null
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results to return (defaults to 100)",
|
|
"default": 100,
|
|
"minimum": 0
|
|
},
|
|
"max_conflict_score": {
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
],
|
|
"format": "float",
|
|
"description": "Maximum conflict score threshold (0.0 to 1.0).\n\nWhen set, only returns results where the resolved conflict_score is <= this value.\nUsed to filter for claims with strong agreement.\n\n- Not set: No conflict filtering (default)\n- 0.2: Only show claims with high agreement\n- 1.0: Show all claims (equivalent to not set)\n\n**Note**: This is a POST-resolution filter. The query executes normally,\nbut results are filtered by conflict score after lens resolution.\nOnly works with materialized views (fast path).",
|
|
"default": null,
|
|
"example": 0.2
|
|
},
|
|
"max_stale": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Maximum acceptable staleness of materialized views in seconds.\n\nWhen set, the fast path (MV lookup) will be skipped if the materialized\nview is older than this threshold. This causes the query to re-compute\nthe result from all candidate assertions.\n\n- Not set: Accept any MV age (default, fastest)\n- 0: Never use cached MV, always compute fresh\n- 60: Only use MV if materialized within the last 60 seconds",
|
|
"default": null,
|
|
"minimum": 0
|
|
},
|
|
"min_conflict_score": {
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
],
|
|
"format": "float",
|
|
"description": "Minimum conflict score threshold (0.0 to 1.0).\n\nWhen set, only returns results where the resolved conflict_score is >= this value.\nUsed to filter for controversial claims where assertions significantly disagree.\n\n- Not set: No conflict filtering (default)\n- 0.7: Only show claims with high conflict (disagreement)\n- 0.0: Show all claims (equivalent to not set)\n\n**Note**: This is a POST-resolution filter. The query executes normally,\nbut results are filtered by conflict score after lens resolution.\nOnly works with materialized views (fast path).",
|
|
"default": null,
|
|
"example": 0.7
|
|
},
|
|
"predicate": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by predicate/relation",
|
|
"default": null
|
|
},
|
|
"since": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int64",
|
|
"description": "Return changelog entries for MV changes since this timestamp.\n\nWhen set, the response includes a `changes_since` list showing winner\nchanges to materialized views that occurred after this timestamp.\nEnables incremental sync: \"What changed since I last checked?\"\n\n- Not set: No changelog (default, backward-compatible)\n- Set: Include MV winner changes since timestamp\n\n**Note**: When `since` is set, the fast path (MV lookup) is bypassed.",
|
|
"default": null,
|
|
"minimum": 0
|
|
},
|
|
"source_class_decay": {
|
|
"type": [
|
|
"boolean",
|
|
"null"
|
|
],
|
|
"description": "Use source-class-aware decay instead of uniform decay.\n\nWhen `true` and `decay_halflife` is also set, each assertion's decay\nis based on its source_class tier (Regulatory=none, Clinical=2yr, etc.).\nFalls back to `decay_halflife` for assertions without source_class.",
|
|
"default": null
|
|
},
|
|
"source_doi": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by source metadata: DOI (Digital Object Identifier).\n\nReturns only assertions whose `source_metadata` JSON contains a `doi`\nfield matching this value (case-insensitive).",
|
|
"default": null,
|
|
"example": "10.1038/xyz"
|
|
},
|
|
"source_journal": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by source metadata: journal name (case-insensitive).\n\nReturns only assertions whose `source_metadata` JSON contains a `journal`\nfield matching this value.\n\nExample: `source_journal=NEJM` returns assertions from New England Journal of Medicine.",
|
|
"default": null,
|
|
"example": "NEJM"
|
|
},
|
|
"source_platform": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by source metadata: platform (e.g., \"PubMed\", \"Reddit\").\n\nReturns only assertions whose `source_metadata` JSON contains a `platform`\nfield matching this value (case-insensitive).",
|
|
"default": null,
|
|
"example": "PubMed"
|
|
},
|
|
"source_study_design": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by source metadata: study design (e.g., \"RCT\", \"observational\").\n\nReturns only assertions whose `source_metadata` JSON contains a `study_design`\nfield matching this value (case-insensitive).",
|
|
"default": null,
|
|
"example": "RCT"
|
|
},
|
|
"subject": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by subject entity",
|
|
"default": null
|
|
},
|
|
"vector_near": {
|
|
"type": [
|
|
"array",
|
|
"null"
|
|
],
|
|
"items": {
|
|
"type": "number",
|
|
"format": "float"
|
|
},
|
|
"description": "Query by semantic vector similarity (k-nearest neighbors).\n\nWhen set, the QueryEngine uses the vector index for candidate retrieval\ninstead of the standard SP/S indexes. This enables semantic similarity\nqueries like \"find assertions with embeddings similar to this one.\"\n\nProvide a JSON array of floats representing the query embedding vector.\nThe dimension must match the vectors stored in the index.\n\n- Not set: Use standard index-based lookup (default)\n- Set: Use vector index for k-NN search\n\n**Note**: When `vector_near` is set, the fast path (MV lookup) is bypassed.\nSubject/predicate filters are applied AFTER vector search.",
|
|
"default": null
|
|
},
|
|
"visual_near": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by visual similarity to a reference pHash (hex-encoded, 16 chars).\n\nReturns assertions whose `visual_hash` has hamming distance <= `visual_threshold`.\nAssertions without a `visual_hash` are excluded when this is set.\n\nExample: `visual_near=a3f2b1c4d5e6f708` finds assertions with similar screenshots.",
|
|
"default": null
|
|
},
|
|
"visual_threshold": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int32",
|
|
"description": "Maximum hamming distance for `visual_near` matching (0-64, default: 8).\n\nLower values require closer visual similarity:\n- 0: Exact match only\n- 8 (default): ~12.5% bit difference, catches resizing/compression\n- 16: ~25% bit difference, more lenient",
|
|
"default": null,
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"QueryParamsAuditDto": {
|
|
"type": "object",
|
|
"description": "Query parameters captured for audit purposes.",
|
|
"properties": {
|
|
"epoch": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by epoch (hex-encoded)"
|
|
},
|
|
"lens": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Lens used for conflict resolution"
|
|
},
|
|
"lifecycle": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/LifecycleDto",
|
|
"description": "Filter by lifecycle stage"
|
|
}
|
|
]
|
|
},
|
|
"predicate": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by predicate/relation"
|
|
},
|
|
"subject": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by subject entity"
|
|
}
|
|
}
|
|
},
|
|
"QueryResponse": {
|
|
"type": "object",
|
|
"description": "Response from a query operation.",
|
|
"required": [
|
|
"assertions",
|
|
"total_count",
|
|
"has_more"
|
|
],
|
|
"properties": {
|
|
"assertions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/AssertionResponse"
|
|
},
|
|
"description": "Matching assertions"
|
|
},
|
|
"changes_since": {
|
|
"type": [
|
|
"array",
|
|
"null"
|
|
],
|
|
"items": {
|
|
"$ref": "#/components/schemas/ChangeEntryDto"
|
|
},
|
|
"description": "Changelog entries for MV changes since the `since` parameter.\nOnly present when `since` parameter was provided."
|
|
},
|
|
"conflict_score": {
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
],
|
|
"format": "float",
|
|
"description": "Degree of disagreement among candidates (0.0 = unanimous, 1.0 = max conflict).\nSee `stemedb_lens::compute_conflict_score()` for the canonical algorithm.\nOnly present when a lens is applied."
|
|
},
|
|
"has_more": {
|
|
"type": "boolean",
|
|
"description": "Whether there are more results beyond the limit"
|
|
},
|
|
"resolution_confidence": {
|
|
"type": [
|
|
"number",
|
|
"null"
|
|
],
|
|
"format": "float",
|
|
"description": "Confidence in the resolution (0.0 to 1.0).\nOnly present when a lens is applied."
|
|
},
|
|
"total_count": {
|
|
"type": "integer",
|
|
"description": "Total number of results returned",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"QuotaStatusResponse": {
|
|
"type": "object",
|
|
"description": "Response containing quota status.",
|
|
"required": [
|
|
"agent_id",
|
|
"remaining",
|
|
"limit",
|
|
"reset_at",
|
|
"used",
|
|
"window_start"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Agent's public key (hex-encoded)"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Total tokens allowed per hour",
|
|
"minimum": 0
|
|
},
|
|
"remaining": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Remaining tokens in current window",
|
|
"minimum": 0
|
|
},
|
|
"reset_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when this quota window resets",
|
|
"minimum": 0
|
|
},
|
|
"used": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Tokens already consumed in current window",
|
|
"minimum": 0
|
|
},
|
|
"window_start": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Current window start timestamp",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"ResetCircuitRequest": {
|
|
"type": "object",
|
|
"description": "Request to reset a circuit breaker.",
|
|
"required": [
|
|
"agent_id"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Hex-encoded agent ID to reset."
|
|
}
|
|
}
|
|
},
|
|
"ResetCircuitResponse": {
|
|
"type": "object",
|
|
"description": "Response for resetting a circuit breaker.",
|
|
"required": [
|
|
"agent_id",
|
|
"message"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Hex-encoded agent ID that was reset."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Success message."
|
|
}
|
|
}
|
|
},
|
|
"ResolutionStatusDto": {
|
|
"type": "string",
|
|
"description": "Resolution status indicating level of agreement.",
|
|
"enum": [
|
|
"Unanimous",
|
|
"Agreed",
|
|
"Contested"
|
|
]
|
|
},
|
|
"ResolveAliasParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for alias resolution.",
|
|
"required": [
|
|
"path"
|
|
],
|
|
"properties": {
|
|
"path": {
|
|
"type": "string",
|
|
"description": "The path to resolve (can be an alias or canonical)"
|
|
},
|
|
"transitive": {
|
|
"type": "boolean",
|
|
"description": "If true, resolve transitively to find all related paths.\nIf false (default), only return the direct canonical."
|
|
}
|
|
}
|
|
},
|
|
"ResolveAliasResponse": {
|
|
"type": "object",
|
|
"description": "Response from alias resolution.",
|
|
"required": [
|
|
"input_path",
|
|
"resolved_paths"
|
|
],
|
|
"properties": {
|
|
"input_path": {
|
|
"type": "string",
|
|
"description": "The original path queried"
|
|
},
|
|
"resolved_paths": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "All resolved paths (includes input, canonical, and transitive aliases if requested)"
|
|
}
|
|
}
|
|
},
|
|
"SetQuotaLimitRequest": {
|
|
"type": "object",
|
|
"description": "Set quota limit for an agent (admin operation).\n\nThis allows setting a custom quota limit for a specific agent.\nTypically used to grant higher quotas to trusted agents or\nlower quotas to rate-limited agents.",
|
|
"required": [
|
|
"agent_id",
|
|
"limit"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Agent's Ed25519 public key (hex-encoded, 64 chars)"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "New quota limit (tokens per hour)",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"SetQuotaLimitResponse": {
|
|
"type": "object",
|
|
"description": "Response for set quota limit operation.",
|
|
"required": [
|
|
"agent_id",
|
|
"limit",
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Agent's public key (hex-encoded)"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "New quota limit that was set",
|
|
"minimum": 0
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Status message"
|
|
}
|
|
}
|
|
},
|
|
"SignatureDto": {
|
|
"type": "object",
|
|
"description": "Agent signature entry.",
|
|
"required": [
|
|
"agent_id",
|
|
"signature",
|
|
"timestamp"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Ed25519 public key of the agent (hex-encoded, 32 bytes)"
|
|
},
|
|
"signature": {
|
|
"type": "string",
|
|
"description": "Ed25519 signature (hex-encoded, 64 bytes)"
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Timestamp when the agent signed (Unix epoch)",
|
|
"minimum": 0
|
|
},
|
|
"version": {
|
|
"type": [
|
|
"integer",
|
|
"null"
|
|
],
|
|
"format": "int32",
|
|
"description": "Signature version (1 = legacy subject:predicate, 2 = content hash). Defaults to 1.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"SkepticQueryParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for the skeptic endpoint.",
|
|
"required": [
|
|
"subject",
|
|
"predicate"
|
|
],
|
|
"properties": {
|
|
"include_source_metadata": {
|
|
"type": "boolean",
|
|
"description": "Include human-readable source metadata in the response.\nWhen true, each source will include label, tier, tier_label, and url."
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate/relation to analyze (required)"
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject entity to analyze (required)"
|
|
}
|
|
}
|
|
},
|
|
"SkepticResponse": {
|
|
"type": "object",
|
|
"description": "Response from the skeptic endpoint.\n\nThis is the \"Trust but Verify\" response that shows all competing claims\ninstead of hiding conflict behind a single winner.",
|
|
"required": [
|
|
"subject",
|
|
"predicate",
|
|
"status",
|
|
"conflict_score",
|
|
"claims",
|
|
"candidates_count",
|
|
"computed_at",
|
|
"lens_name"
|
|
],
|
|
"properties": {
|
|
"candidates_count": {
|
|
"type": "integer",
|
|
"description": "Total number of candidate assertions considered",
|
|
"minimum": 0
|
|
},
|
|
"claims": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ClaimSummaryDto"
|
|
},
|
|
"description": "All distinct claims, ranked by weight_share descending"
|
|
},
|
|
"computed_at": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when this view was computed",
|
|
"minimum": 0
|
|
},
|
|
"conflict_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Conflict score (0.0 = unanimous, 1.0 = chaos)",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
},
|
|
"lens_name": {
|
|
"type": "string",
|
|
"description": "Which lens was used (always \"Skeptic\")"
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "The predicate that was queried"
|
|
},
|
|
"status": {
|
|
"$ref": "#/components/schemas/ResolutionStatusDto",
|
|
"description": "Overall resolution status"
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "The subject that was queried"
|
|
}
|
|
}
|
|
},
|
|
"SourceClassDto": {
|
|
"type": "string",
|
|
"description": "Source authority tier classification.\n\nSources are tiered from most authoritative (Regulatory, Tier 0) to\nleast authoritative (Anecdotal, Tier 5). This enables indexing by\ntier and tier-based decay rates.",
|
|
"enum": [
|
|
"Regulatory",
|
|
"Clinical",
|
|
"Observational",
|
|
"Expert",
|
|
"Community",
|
|
"Anecdotal"
|
|
]
|
|
},
|
|
"SourceMetadataDto": {
|
|
"type": "object",
|
|
"description": "Compact source metadata for enriching skeptic/query responses.\n\nThis is a lightweight version of SourceRecordDto used when\nenriching assertion responses with source metadata.",
|
|
"required": [
|
|
"label",
|
|
"tier",
|
|
"tier_label",
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": "Human-readable label for the source."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Current status (active, deprecated, quarantined)."
|
|
},
|
|
"tier": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "Authority tier (0-5).",
|
|
"minimum": 0
|
|
},
|
|
"tier_label": {
|
|
"type": "string",
|
|
"description": "Human-readable tier label."
|
|
},
|
|
"url": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Optional URL where the source can be accessed."
|
|
}
|
|
}
|
|
},
|
|
"SourceSummaryDto": {
|
|
"type": "object",
|
|
"description": "Source provenance summary.",
|
|
"required": [
|
|
"source_hash"
|
|
],
|
|
"properties": {
|
|
"source_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the source document (hex-encoded)"
|
|
},
|
|
"source_metadata": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/SourceMetadataDto",
|
|
"description": "Human-readable source metadata (only present when include_source_metadata=true)"
|
|
}
|
|
]
|
|
},
|
|
"visual_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Visual anchor hash (hex-encoded, optional)"
|
|
}
|
|
}
|
|
},
|
|
"StoreSourceRequest": {
|
|
"type": "object",
|
|
"description": "Request to store a source document.\n\nSource documents are content-addressed: the same content always produces\nthe same hash. Re-uploading identical content is idempotent.",
|
|
"required": [
|
|
"content",
|
|
"content_type"
|
|
],
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "The source document content (base64-encoded for binary safety).\nMaximum size: 10MB after decoding.",
|
|
"example": "VGhpcyBpcyBhIHNvdXJjZSBkb2N1bWVudC4="
|
|
},
|
|
"content_type": {
|
|
"type": "string",
|
|
"description": "MIME type of the content (e.g., \"application/pdf\", \"text/plain\").",
|
|
"example": "text/plain"
|
|
}
|
|
}
|
|
},
|
|
"StoreSourceResponse": {
|
|
"type": "object",
|
|
"description": "Response from storing a source document.",
|
|
"required": [
|
|
"hash",
|
|
"size",
|
|
"status"
|
|
],
|
|
"properties": {
|
|
"hash": {
|
|
"type": "string",
|
|
"description": "BLAKE3 hash of the content (hex-encoded, 64 chars = 32 bytes).\nUse this as `source_hash` when creating assertions."
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "Size of the stored content in bytes.",
|
|
"minimum": 0
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Status message (\"stored\")."
|
|
}
|
|
}
|
|
},
|
|
"SuggestAliasesResponse": {
|
|
"type": "object",
|
|
"description": "Response listing alias suggestions.",
|
|
"required": [
|
|
"input_path",
|
|
"suggestions"
|
|
],
|
|
"properties": {
|
|
"input_path": {
|
|
"type": "string",
|
|
"description": "The input path that suggestions are for"
|
|
},
|
|
"suggestions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/AliasSuggestion"
|
|
},
|
|
"description": "List of suggestions"
|
|
}
|
|
}
|
|
},
|
|
"SupersedeRequest": {
|
|
"type": "object",
|
|
"description": "Request to supersede an assertion (error correction).\n\nSupersession enables error correction without violating append-only semantics.\nInstead of mutating an assertion, we create a supersession record that points\nfrom the old (target) to the new (replacement) assertion.",
|
|
"required": [
|
|
"target_hash",
|
|
"supersession_type",
|
|
"reason",
|
|
"agent_id",
|
|
"signature"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Public key of the agent creating the supersession (hex-encoded, 32 bytes)"
|
|
},
|
|
"new_hash": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Hash of the replacement assertion (hex-encoded, 32 bytes, optional)\nNone for RequiresReview (flagging, not replacing) or pure invalidation."
|
|
},
|
|
"reason": {
|
|
"type": "string",
|
|
"description": "Human-readable explanation (for audit trail)"
|
|
},
|
|
"signature": {
|
|
"type": "string",
|
|
"description": "Signature over the supersession content (hex-encoded, 64 bytes)\nSigns: BLAKE3(target_hash || type || reason || new_hash || timestamp)"
|
|
},
|
|
"supersession_type": {
|
|
"$ref": "#/components/schemas/SupersessionTypeDto",
|
|
"description": "How the target is being superseded"
|
|
},
|
|
"target_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the assertion being superseded (hex-encoded, 32 bytes)"
|
|
}
|
|
}
|
|
},
|
|
"SupersedeResponse": {
|
|
"type": "object",
|
|
"description": "Response from creating a supersession.",
|
|
"required": [
|
|
"status",
|
|
"target_hash",
|
|
"supersession_type",
|
|
"timestamp"
|
|
],
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Status message"
|
|
},
|
|
"supersession_type": {
|
|
"$ref": "#/components/schemas/SupersessionTypeDto",
|
|
"description": "Type of supersession applied"
|
|
},
|
|
"target_hash": {
|
|
"type": "string",
|
|
"description": "Hash of the target assertion that was superseded (hex-encoded)"
|
|
},
|
|
"timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Unix timestamp when the supersession was recorded",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"SupersessionTypeDto": {
|
|
"type": "string",
|
|
"description": "Type of supersession (epoch or assertion).\n\nDetermines how old knowledge should be treated when superseded.",
|
|
"enum": [
|
|
"Invalidate",
|
|
"Temporal",
|
|
"Refinement",
|
|
"RequiresReview",
|
|
"Additive"
|
|
]
|
|
},
|
|
"TierResolutionDto": {
|
|
"type": "object",
|
|
"description": "Per-tier resolution result from LayeredConsensus lens.\n\nRepresents the consensus within a single source class tier.",
|
|
"required": [
|
|
"tier",
|
|
"source_class",
|
|
"candidates_count",
|
|
"conflict_score",
|
|
"resolution_confidence"
|
|
],
|
|
"properties": {
|
|
"candidates_count": {
|
|
"type": "integer",
|
|
"description": "Number of candidates in this tier.",
|
|
"minimum": 0
|
|
},
|
|
"conflict_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Within-tier conflict score (0.0 = unanimous, 1.0 = max conflict).",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
},
|
|
"resolution_confidence": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "Within-tier resolution confidence (0.0 to 1.0).",
|
|
"maximum": 1,
|
|
"minimum": 0
|
|
},
|
|
"source_class": {
|
|
"$ref": "#/components/schemas/SourceClassDto",
|
|
"description": "The source class for this tier."
|
|
},
|
|
"tier": {
|
|
"type": "integer",
|
|
"format": "int32",
|
|
"description": "The tier number (0-5). Lower = higher authority.",
|
|
"minimum": 0
|
|
},
|
|
"winner": {
|
|
"oneOf": [
|
|
{
|
|
"type": "null"
|
|
},
|
|
{
|
|
"$ref": "#/components/schemas/AssertionResponse",
|
|
"description": "The winning assertion from within-tier consensus, if any candidates."
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"TraceParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for the trace endpoint.\n\nReturns a filtered list of query audits for debugging agent decision-making.\nAll parameters are optional filters that narrow down results.",
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Filter by agent public key (hex-encoded, 32 bytes) - required",
|
|
"default": ""
|
|
},
|
|
"from": {
|
|
"type": "string",
|
|
"description": "Start of time range (Unix timestamp or ISO8601) - required",
|
|
"default": ""
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of results (default: 100)",
|
|
"default": 100,
|
|
"minimum": 0
|
|
},
|
|
"subject": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filter by subject pattern (e.g., \"Tesla*\", \"auth/*\")",
|
|
"default": null
|
|
},
|
|
"to": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "End of time range (Unix timestamp or ISO8601, defaults to now)",
|
|
"default": null
|
|
}
|
|
}
|
|
},
|
|
"TraceResponse": {
|
|
"type": "object",
|
|
"description": "Response from the trace endpoint.\n\nReturns query audits matching the trace filters, useful for debugging\nwhy an agent made specific decisions.",
|
|
"required": [
|
|
"audits",
|
|
"total_count",
|
|
"agent_id",
|
|
"from_timestamp",
|
|
"to_timestamp"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Agent ID that was traced (hex-encoded)"
|
|
},
|
|
"audits": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/QueryAuditResponse"
|
|
},
|
|
"description": "Matching query audit records"
|
|
},
|
|
"from_timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Time range start (Unix timestamp)",
|
|
"minimum": 0
|
|
},
|
|
"to_timestamp": {
|
|
"type": "integer",
|
|
"format": "int64",
|
|
"description": "Time range end (Unix timestamp)",
|
|
"minimum": 0
|
|
},
|
|
"total_count": {
|
|
"type": "integer",
|
|
"description": "Total number of results returned",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"TrippedCircuitsParams": {
|
|
"type": "object",
|
|
"description": "Query parameters for listing tripped circuits.",
|
|
"properties": {
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of circuits to return (default: 100).",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"TrippedCircuitsResponse": {
|
|
"type": "object",
|
|
"description": "Response for listing tripped circuit breakers.",
|
|
"required": [
|
|
"circuits",
|
|
"count"
|
|
],
|
|
"properties": {
|
|
"circuits": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/CircuitBreakerStatusResponse"
|
|
},
|
|
"description": "List of tripped circuits."
|
|
},
|
|
"count": {
|
|
"type": "integer",
|
|
"description": "Total count of tripped circuits.",
|
|
"minimum": 0
|
|
}
|
|
}
|
|
},
|
|
"TrustTierDto": {
|
|
"type": "string",
|
|
"description": "Trust tier names for API responses.",
|
|
"enum": [
|
|
"Untrusted",
|
|
"Limited",
|
|
"Verified",
|
|
"Trusted",
|
|
"Authority"
|
|
]
|
|
},
|
|
"VerificationResult": {
|
|
"type": "object",
|
|
"description": "Result of verifying an agent against a gold standard.",
|
|
"required": [
|
|
"subject",
|
|
"predicate",
|
|
"correct",
|
|
"agent_answer",
|
|
"expected_answer",
|
|
"trust_adjustment",
|
|
"new_trust_score"
|
|
],
|
|
"properties": {
|
|
"agent_answer": {
|
|
"type": "string",
|
|
"description": "The agent's answer."
|
|
},
|
|
"correct": {
|
|
"type": "boolean",
|
|
"description": "Whether the agent's answer was correct."
|
|
},
|
|
"expected_answer": {
|
|
"type": "string",
|
|
"description": "The expected answer."
|
|
},
|
|
"new_trust_score": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "The agent's new trust score."
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject entity."
|
|
},
|
|
"trust_adjustment": {
|
|
"type": "number",
|
|
"format": "float",
|
|
"description": "The trust adjustment that was applied."
|
|
}
|
|
}
|
|
},
|
|
"VerifyAgentRequest": {
|
|
"type": "object",
|
|
"description": "Request to verify an agent against all gold standards.",
|
|
"required": [
|
|
"agent_id",
|
|
"subject",
|
|
"predicate",
|
|
"agent_object"
|
|
],
|
|
"properties": {
|
|
"agent_id": {
|
|
"type": "string",
|
|
"description": "Hex-encoded agent ID (32 bytes)."
|
|
},
|
|
"agent_object": {
|
|
"type": "string",
|
|
"description": "The agent's proposed answer."
|
|
},
|
|
"predicate": {
|
|
"type": "string",
|
|
"description": "Predicate of the gold standard to verify against."
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "Subject of the gold standard to verify against."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"tags": [
|
|
{
|
|
"name": "assertions",
|
|
"description": "Create and manage assertions"
|
|
},
|
|
{
|
|
"name": "epochs",
|
|
"description": "Create and manage epochs (paradigms)"
|
|
},
|
|
{
|
|
"name": "votes",
|
|
"description": "Create votes on assertions"
|
|
},
|
|
{
|
|
"name": "query",
|
|
"description": "Query assertions with filters and lenses"
|
|
},
|
|
{
|
|
"name": "health",
|
|
"description": "Health check endpoint"
|
|
},
|
|
{
|
|
"name": "audit",
|
|
"description": "Query audit trail for incident investigation"
|
|
},
|
|
{
|
|
"name": "supersession",
|
|
"description": "Supersede assertions for error correction"
|
|
},
|
|
{
|
|
"name": "meter",
|
|
"description": "Economic throttling and quota management"
|
|
},
|
|
{
|
|
"name": "provenance",
|
|
"description": "Source document storage and retrieval"
|
|
},
|
|
{
|
|
"name": "admin",
|
|
"description": "Administrative operations for system maintenance"
|
|
},
|
|
{
|
|
"name": "concepts",
|
|
"description": "ConceptPath and alias management for cross-scheme resolution"
|
|
},
|
|
{
|
|
"name": "admission",
|
|
"description": "Admission control and PoW requirements"
|
|
},
|
|
{
|
|
"name": "quarantine",
|
|
"description": "Content defense quarantine management"
|
|
},
|
|
{
|
|
"name": "circuit_breaker",
|
|
"description": "Per-agent circuit breaker management"
|
|
}
|
|
]
|
|
} |