Jev API Quickstart: Build Your First Decision Path
A useful first call proves more than connectivity. It establishes the request boundary, the meaning of a Noul probability, and the logging needed to turn an example into a reproducible integration.
Make the first experiment deliberately small
Start with one short piece of state and one yes-or-no proposition whose answer a reviewer could label. A support message and “Does this customer explicitly request a refund?” is better than a broad request to decide the ticket's outcome. The narrow example exposes the complete API loop without hiding confusion behind several questions. It also gives you an obvious manual check when the first response arrives.
The HTTP surface is a POST to the System One endpoint with bearer authentication and JSON. The payload selects a model, supplies state, and maps your own question key to a typed question. Keep the API key in an environment variable or secret manager, never in the payload or client bundle. Run the call from a server-side process because a browser-distributed key is already compromised, regardless of whether the first demo contains sensitive data.
The question key is a handle, not an instruction
A key such as refund_requested lets code retrieve the answer, but the independent guide notes that the real instruction belongs inside the question definition. Do not rely on a clever field name to communicate meaning to the model. Write a complete, literal proposition and define ambiguous terms. If “recent” means thirty days or “enterprise” means a particular plan flag, say so—or compute the condition deterministically before calling the model.
Criteria are especially useful near boundaries. State what counts as true and what counts as false, including how silence should be treated. Still, avoid asking the model to reproduce database logic. If the record already contains days_since_last_charge or plan_tier, ordinary comparisons will be cheaper and exact. The model earns its place when the evidence is linguistic or otherwise difficult to reduce to rules.
Read a Noul as belief, not as a rating
A Noul returns a value between zero and one for the proposition being true. A result near 0.5 means the available evidence does not favor either side; it is not “medium refund intent.” This distinction prevents a common category error. If the business concept is genuinely an ordered spectrum such as severity or frustration, use a Score with named levels rather than stretching a Boolean probability into a scale.
The number is not a decision by itself. A route may use a high threshold when false positives are costly, a lower threshold when the result only changes sorting, or two thresholds that create an uncertain review band. Choose these values from labelled production-like examples. The numerical output shown in documentation is an illustration of one response, not a guarantee that your call—or even the same example on a later model—will reproduce it.
Log the response that actually served you
Capture the versioned model identifier returned by the service, not only the alias sent in the request. Once a threshold depends on a probability distribution, model version becomes part of the decision record. Also log your question-definition revision, request ID, latency, token usage, answer value, and final application action. Avoid copying secrets or unnecessary personal data into logs; use stable record identifiers and approved redaction instead.
This first telemetry schema pays for itself during the first disagreement. It lets the team distinguish a moved alias from changed input construction, a network retry from a slow model response, and a correct model judgment from a policy bug after the call. If the application only records “routed to billing,” it has thrown away the evidence needed to evaluate the probabilistic component.
SDKs should preserve the same contract
The Python and TypeScript SDKs provide classes or helpers for typed questions, environment-based authentication, and response objects. Use them to reduce transport boilerplate, but keep an HTTP example in an integration test or runbook. It makes the actual wire contract visible and provides a diagnostic path when an SDK release changes serialization, retry behavior, or defaults. Confirm runtime requirements and package versions in the current official SDK documentation.
Whichever client you choose, set a deadline and handle authentication errors, invalid requests, rate limits, transient server failures, and a permanently unavailable service as distinct cases. A model call on the request path needs an explicit failure policy. Depending on consequence, that may mean retaining the existing route, placing work in a review queue, or returning a temporary error. It should not mean silently treating missing output as false.
Turn the sample into an evaluation fixture
Replace the single hand-written message with a small, labelled set drawn from the domain. Include clear positives, clear negatives, ambiguous cases, missing evidence, adversarial wording, and important demographic or language segments where appropriate. Run the pinned model over the set and retain raw probabilities. This establishes a baseline for threshold selection and creates a regression test for model or question changes.
The independent tutorial highlights a launch-week report where an official example did not reproduce the documented category. The cause could have been documentation, version drift, or environment details; the general lesson is sound without deciding which. Examples teach request shape. Only runs in your own environment measure behavior. A successful first call is therefore the beginning of validation, not evidence that the integration is ready to automate consequential work.
What to carry into your next build
- Begin with one labelable proposition and keep credentials on the server.
- Put meaning in the question instructions and criteria, not only in the map key.
- Interpret Noul as a probability of truth and derive thresholds from labelled examples.
- Log the served model version, probability, question revision, usage, and resulting action.
Editorial method and source note
This article is an original synthesis based on Learn Jev's “Your First Jev Call,” with endpoint, model, and primitive concepts checked against TypeSafe's official documentation. Learn Jev is an independent launch-week guide, not the service operator; its sample values and reported reproduction discrepancy are contextual evidence, not guaranteed current behavior. No source text, code sample, or article structure is reproduced.
Facts and product details should be checked against the linked source and current official documentation before making production decisions.