Skip to main content

​
GET /query

Query the oracle for the liveness status of a target node. Returns confidence scores for whether the node is alive, dead, or unknown, along with evidence and partition state information.

​
Query Parameters

​
target
uint64
required
The ID of the node to query liveness status for

​
Response

​
target
uint64
The ID of the queried target node
​
alive_confidence
float64
Confidence score that the target node is alive (0.0 to 1.0)
​
dead_confidence
float64
Confidence score that the target node is dead (0.0 to 1.0)
​
unknown
float64
Confidence score representing uncertainty about the node’s status (0.0 to 1.0)
​
refused
boolean
Whether the oracle refused to provide a determination
​
refusal_reason
string
Explanation for why the query was refused (only present if refused is true)
​
dead
boolean
Final determination of whether the node is considered dead
​
witness_count
integer
Number of witnesses that contributed to this determination
​
disagreement
float64
Measure of disagreement among witnesses (0.0 to 1.0)
​
partition_state
string
Current partition state assessment for the target node
​
evidence
array
List of evidence strings supporting the determination

​
Response Example

{
  "target": 42,
  "alive_confidence": 0.85,
  "dead_confidence": 0.10,
  "unknown": 0.05,
  "refused": false,
  "dead": false,
  "witness_count": 5,
  "disagreement": 0.15,
  "partition_state": "HEALTHY",
  "evidence": [
    "witness 1 reports alive",
    "witness 2 reports alive"
  ]
}

​
Error Codes

​
400 Bad Request
error
  • Missing target parameter
  • Invalid target ID format (must be valid uint64)
​
405 Method Not Allowed
error
Request method is not GET

​
cURL Example

curl "http://localhost:8080/query?target=42"

Build docs developers (and LLMs) love

Get started for freeTalk to us