A prediction oracle API is an interface for asking a defined question and receiving an estimate, answer, or resolution with enough context to interpret it. The term does not describe one universal protocol. It can refer to a forecasting service, a question-answering system, an interface to a resolution mechanism, or a combination of those components.
The design challenge is to make the type of answer unmistakable. A probability about the future is not an observed fact. A proposed settlement is not a finalized outcome. A generated explanation is not evidence by itself. This guide proposes a conceptual response model that keeps those differences visible. The example files on this site are static fixtures, not live endpoints or an operational forecasting service.
Define what the service is allowed to answer
Start by stating the supported question class. A weather forecast, a supply-chain estimate, and a binary event resolution have different data requirements. An interface that accepts arbitrary questions still needs a way to reject questions outside its supported scope. Returning a polished answer to everything can make unsupported outputs look authoritative.
For a fictional publication forecast, define the event, deadline, timezone, and acceptable interpretation. Ask whether the service estimates occurrence, reports evidence, or returns a final resolution. Keep these modes separate even when they share a common question identifier.
A useful documentation page includes examples of questions the service will not answer. Unsupported geography, insufficient evidence, ambiguous wording, or an expired forecast horizon can all justify a nonanswer. Explicit boundaries are easier for client developers to handle than inconsistent guesses.
Use a typed answer envelope
An answer envelope should identify the question, answer type, status, relevant time, and interpretation of the value. For a forecast, it might include a probability and forecast horizon. For an observation, it might include units and observation time. For a resolution, it might include the accepted outcome and finality state.
Do not treat this proposed envelope as an established industry standard. It is a design exercise intended to prevent accidental type mixing. Our Oracle API section provides local JSON fixtures that demonstrate the distinction without contacting an external service.
Use machine-readable values for status and schema version. Avoid making clients infer state by parsing explanatory prose. A human-readable explanation can be helpful, but the client should know whether a response is pending, unsupported, provisional, or final without interpreting the tone of that explanation.
Define probability in relation to a specific event
A probability needs a clearly defined event and horizon. “Sixty percent likely” is incomplete without knowing what event is being evaluated and by when. Specify whether the estimate applies to occurrence during a period, occurrence by a deadline, or a particular state at an instant.
For a binary question, represent the probability on a documented scale, such as a value between zero and one. Validate the range and numeric type. A missing probability should remain missing rather than becoming zero through default conversion. Zero expresses a substantive estimate; absence expresses a different state.
For multiple outcomes, document whether they are mutually exclusive and collectively exhaustive. Only then does a sum-to-one constraint make sense. Overlapping events may legitimately have probabilities whose sum exceeds one. The schema should express the relationship among outcomes rather than imposing an inappropriate normalization rule.
Preserve the information available at prediction time
A forecast record should distinguish when it was issued from the deadline it predicts. It may also need a data cutoff that indicates the latest information permitted in producing the estimate. Preserve earlier forecasts when a new one is issued so that later evaluation does not accidentally use information from the future.
Consider a fictional forecast issued Monday for an event expected Friday. A revision on Thursday should be a new record, not a silent replacement of Monday's estimate. Each record can share the same question identifier while retaining its own issue time, model version, and input snapshot identity.
This design supports reproducible evaluation. A reviewer can compare the estimate that existed at the relevant time with the eventual outcome. Without that history, a service can appear more accurate simply because its earlier mistakes have disappeared from the accessible record.
Separate explanation from evidence
An explanation describes why an answer was produced. Evidence describes the material that supports a claim. They can overlap, but they are not interchangeable. A confident narrative should not be treated as a verified observation merely because it is detailed or fluently written.
For a source-backed answer, retain identifiers for the relevant evidence and the time it was retrieved. For a model-derived forecast, record enough information about the method and version to interpret later changes. Avoid exposing private training data, credentials, or restricted material in a public response.
Where evidence is incomplete or conflicting, make that state visible. A client may choose to display a qualified answer, request review, or decline an automated action. The API should provide the information needed for that choice rather than forcing the client to equate every successful HTTP response with a reliable conclusion.
Evaluate forecasts rather than advertising certainty
A practical evaluation plan starts with a set of resolved questions and the forecasts made before their outcomes were known. Keep an untouched evaluation set or a time-based holdout appropriate to the forecasting task. Compare the method with a simple baseline, and record how unresolved or invalid questions are excluded.
For binary outcomes, one transparent calculation is the mean squared difference between each probability and its realized zero-or-one outcome. This is the Brier score; see the forecast verification note for background. The formula can be inspected directly: predictions closer to the realized outcome contribute smaller squared errors. A single example is not enough to establish the quality of a forecasting system.
Also inspect calibration by grouping comparable forecasts. Estimates near a given probability should be evaluated across enough relevant cases to judge their observed outcome frequency. Small samples, changing question mixes, and selective publication can make apparently impressive results misleading. Report the evaluation context alongside any summary metric.
Make unavailable and unresolved states first-class
Use explicit response states for insufficient evidence, an unsupported question, an expired forecast, a pending resolution, and a temporary service failure. These states should not all collapse into an empty object. A client may need different retry or display behavior for each one.
Distinguish a transport error from a domain answer. A request can complete successfully while the correct domain result is “unresolved.” Conversely, an interrupted request does not establish that the forecast itself is unavailable everywhere. Document what the response means and what the client may safely infer.
For integrations with optimistic settlement, retain the distinction between proposed and finalized answers. The UMA resolution reference supplies one documented example of an assertion-and-dispute process. Its status model should not be flattened into an ordinary forecast probability.
Keep the consumer from making stronger claims
Document which uses the response supports. A probability can inform a display or an analysis without automatically authorizing an irreversible action. A source-backed answer can identify a reported fact without establishing that every upstream source is correct. Clients should not promote qualified outputs into unconditional guarantees.
Version the schema and define how clients encounter unsupported versions. Preserve stable question identifiers across revisions, but give materially changed rules a distinct version. A change in the meaning of an event is not merely a cosmetic text update.
Use the Prediction Oracles section to choose the answer type and the Prediction Market Oracle section when final settlement is involved. The best interface makes it difficult to confuse the two.
Conclusion: return context with the answer
A prediction oracle API earns its usefulness through clarity about what was asked, what was returned, when the estimate applies, and what evidence or method supports it. Explicit uncertainty and nonanswer states are features of a reliable interface, not signs that the design is unfinished.
Explore the Prediction Oracle API overview and inspect the local example responses. They provide a starting point for a schema review while keeping forecasts, observations, and final outcomes separate from the beginning.
