JEV AI · DEVELOPER REFERENCE

Jev AI documentation

Call the hosted Jev decision API with text and typed questions. This reference covers the wire format, response fields, account headers, and failure handling. Use the API key page to create a key.

Base URL https://jev-ai.pro/api · Evaluation POST /v1/systemone

Authentication

Create an API key in your Jev AI account. Send it in the Authorization header on every API call. A Jev AI key belongs to this site; keep it in a server environment variable and revoke it if exposed.

Store it as JEV_AI_API_KEY in your local server environment and deployment secrets. Fail early if it is missing, as shown in the SDK example. Never put the key in browser code, logs, commits or chat; configure it directly in your environment.

The playground uses a signed-in browser session. The public API uses a Bearer key, not that session cookie.

Endpoint and request headers

Send a JSON body to POST https://jev-ai.pro/api/v1/systemone. The endpoint evaluates all named questions against the same state in one request.

POST /api/v1/systemone HTTP/1.1
Host: jev-ai.pro
Authorization: Bearer <JEV_AI_API_KEY>
Content-Type: application/json
Accept: application/json

Authorization and Content-Type are the headers to include in your client. Accept is optional.

TypeSafe Official SDK: set the Jev AI base URL

@typesafe-ai/sdk is the official JavaScript / TypeScript SDK published by TypeSafe. Jev AI independently provides a compatible hosted API endpoint; this SDK is not published by Jev AI.

Already using the official TypeSafe SDK? Update both the key and the base URL. The SDK defaults to TypeSafe's service. A Jev AI key and balance belong to Jev AI; changing only the key does not switch the service receiving your requests.

For @typesafe-ai/sdk in JavaScript / TypeScript, explicitly set baseURL: 'https://jev-ai.pro/api' in the client your application actually uses, along with your server-side JEV_AI_API_KEY.

If your project already uses the SDK, reuse its client and inspect any wrappers, constructor overrides and environment settings. Pair the Jev AI key with the Jev AI endpoint; do not send it to TypeSafe's default service or automatically fall back to another provider.

Keep /api in the base URL. Do not add /v1 or /systemone there, or the SDK will construct the wrong path. For another SDK language or version, check its base-address option name and confirm the final URL above.

// Official TypeSafe SDK, published by TypeSafe — @typesafe-ai/sdk 0.6.0
// Server-side JavaScript / TypeScript using the Jev AI compatible endpoint
import { TypeSafeClient, choice } from '@typesafe-ai/sdk'

const apiKey = process.env.JEV_AI_API_KEY
if (!apiKey) throw new Error('Set JEV_AI_API_KEY on your server')

const client = new TypeSafeClient({
  apiKey,
  baseURL: 'https://jev-ai.pro/api', // Required, including for existing SDK users
  retry: { maxRetries: 0 }, // Avoid replaying a request with an uncertain outcome
})

// The SDK appends /v1/systemone to baseURL.
const response = await client.systemOne({
  model: 'jev-latest',
  state: { document: 'I was charged twice. Please fix this ASAP.' },
  questions: {
    category: choice('What is this ticket about?', { billing: null, technical: null, other: null }),
  },
})
console.log(response.answers.category.choice)

This example disables automatic retries so a request with an uncertain outcome is not replayed. The model call uses your account balance.

Check the connection before inference

1. Set your Jev AI key on the server. Update the SDK client configuration in both local and deployment environments, then restart or redeploy the application.
2. Run the authenticated model lookup below. It checks connectivity and authentication without running the model. It does not guarantee that a later inference call will succeed.
3. Confirm your application's resolved SDK destination is also https://jev-ai.pro/api; a successful cURL check does not update the application client for you. Check for constructor overrides or stale environment settings.
4. Send one small decision request, inspect its answers and usage, then check your Jev AI API usage. Keep keys and Authorization headers out of logs and support messages.

curl https://jev-ai.pro/api/v1/models \
  -H "Authorization: Bearer $JEV_AI_API_KEY"

If you get 401, check both the destination host and the Jev AI key. For 404, check for a missing /api or repeated /v1. Resolve configuration errors before sending more decision requests.

For automated checks, mock the transport and assert the final request URL, Bearer authentication and response parsing. Record the SDK version, configuration locations and destination host/path when troubleshooting, without logging keys or Authorization headers.

Copy the coding-agent setup prompt to have your agent inspect the existing integration and configure the endpoint.

For repository research, install jevgrep with our API adapter and its built-in agent skill. The skill teaches your coding agent to gather source context with jg.

Decisions API compatibility

Send POST https://jev-ai.pro/api/alpha/decisions with your Jev AI Bearer key. This additional endpoint accepts the Decisions request and answer format: model, state, and questions, with noul, choice, and score answers. All three fields are required. The existing /api/v1/systemone endpoint keeps its current behavior.

curl --fail-with-body https://jev-ai.pro/api/alpha/decisions \
  -H "Authorization: Bearer $JEV_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"~typesafe/jev-latest","state":"My payment failed.","questions":{"billing":{"type":"noul","instructions":"Is this about billing?"}}}'

Jev model aliases are ~typesafe/jev-latest → jev-latest, and typesafe/jev-1.13 or typesafe/jev-1.13-20260917 → jev-1.13.0. Existing Jev and connected Laya model IDs also work. Saved judges accept judgeId and optional revision instead of questions.

OpenRouter SDK setup

This example uses @openrouter/[email protected] with the Jev AI key and destination. Set serverURL on the individual alpha.decisions.create call as shown: in this SDK version, setting it only on the client constructor does not redirect this operation. Use the site origin without /api; the SDK adds /api/alpha/decisions. Keep the key server-side and disable automatic retries for calls with an uncertain outcome.

import { OpenRouter } from '@openrouter/sdk';

const apiKey = process.env.JEV_AI_API_KEY;
if (!apiKey) throw new Error('Set JEV_AI_API_KEY on your server.');
const client = new OpenRouter({
  apiKey,
  serverURL: 'https://jev-ai.pro',
  retryConfig: { strategy: 'none' },
});

const result = await client.alpha.decisions.create({
  decisionsRequest: {
    model: '~typesafe/jev-latest',
    state: 'My payment failed.',
    questions: {
      billing: { type: 'noul', instructions: 'Is this about billing?' },
    },
  },
}, {
  // This SDK operation needs its own serverURL override.
  serverURL: 'https://jev-ai.pro',
  retries: { strategy: 'none' },
});

console.log(result.answers.billing);
console.log(result.usage.inputTokens);

Response and billing

The response includes id, the resolved model, provider, answers, and usage.input_tokens / usage.output_tokens. The SDK reads token fields as inputTokens / outputTokens. provider identifies this hosted service, Jev AI.

Billing follows the existing API: paid input tokens first, then one credit for the whole request when tokens are insufficient; output tokens are free. Raw HTTP responses also include billing.mode, billing.input_tokens_charged, and billing.credits_charged. Existing billing headers remain available.

The optional usage.cost field is omitted because prepaid tokens, different plans, and gift credits do not have one per-call USD value. Treat missing cost as unavailable, never as zero. Code that requires a USD cost must use its own billing policy. The SDK may discard our additional billing field; use raw HTTP or the billing headers for these balance units.

Metadata and errors

session_id and user accept nonempty strings up to 256 characters. The body session_id takes precedence over x-session-id. trace accepts an object up to 64 fields and 8192 bytes; known trace labels are strings up to 256 characters. These fields are stored privately with the run and are not sent to inference providers or broadcast destinations. user is a client label and never changes the authenticated account.

Provider routing preferences are unsupported: a non-null provider receives 400. Unknown request fields are rejected. The complete JSON body limit remains 256000 bytes, with at most 64 questions.

Failures return their HTTP status with { "error": { "code": 401, "message": "…" } }. Validation remains 422, insufficient balance is 402, and rate limits are 429. Honor Retry-After when present. A confirmed failed run returns its reserved balance through the same refund flow as the existing endpoint.

Request body

The example checks a generated claim against a source excerpt. The question IDs, support and number_mismatch, become keys in answers.

{
  "model": "jev-latest",
  "state": {
    "claim": "The study found a 40% productivity increase.",
    "source_excerpt": "The home-working group showed a 13% performance increase."
  },
  "questions": {
    "support": {
      "type": "choice",
      "instructions": "Does the source excerpt support the claim?",
      "criteria": {
        "supported": "The excerpt states the same finding.",
        "contradicted": "The excerpt gives a different finding.",
        "not_addressed": "The excerpt does not discuss the claim."
      }
    },
    "number_mismatch": {
      "type": "noul",
      "instructions": "Do the figures in the claim and excerpt differ?"
    }
  }
}

curl --fail-with-body https://jev-ai.pro/api/v1/systemone \
  -H "Authorization: Bearer $JEV_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"jev-latest","state":{"claim":"The study found a 40% productivity increase.","source_excerpt":"The home-working group showed a 13% performance increase."},"questions":{"support":{"type":"choice","instructions":"Does the source excerpt support the claim?","criteria":{"supported":"The excerpt states the same finding.","contradicted":"The excerpt gives a different finding.","not_addressed":"The excerpt does not discuss the claim."}},"number_mismatch":{"type":"noul","instructions":"Do the figures in the claim and excerpt differ?"}}}'

Question types

Each question needs a type and instructions. IDs may use letters, digits, dots, dashes, and underscores. Choose the answer shape your application can act on.

Response JSON

A successful response contains the resolved model, one answer per question ID, and token usage. The values below illustrate the shape; run the request for actual model output.

{
  "model": "jev-1.13.0",
  "answers": {
    "support": {
      "type": "choice",
      "choice": "contradicted",
      "probabilities": {
        "supported": 0.01,
        "contradicted": 0.98,
        "not_addressed": 0.01
      },
      "confidence": 0.98
    },
    "number_mismatch": {
      "type": "noul",
      "noul": 0.99
    }
  },
  "usage": {
    "input_tokens": 136,
    "output_tokens": 18
  }
}

For choice, use the selected label for routing and inspect the distribution when deciding whether to review. A noul value expresses yes probability; your code chooses any action threshold.

Billing response headers

Jev API calls use available paid input tokens first. Token charges are actual input tokens × the model multiplier. If those are insufficient, the entire request uses the model’s credit charge. A single request never charges both balances; output tokens are free.

See pricing for current plans and allowances.

Models and limits

Use jev-latest for the stable Jev alias, jev-preview for the latest preview, or pin jev-1.13.0. GET /api/v1/models returns the models currently exposed to your authenticated account.

• Maximum JSON request body: 256000 bytes.
• Maximum questions per request: 64; each question ID is at most 64 characters.
• Account rate limit: 1000 API requests per minute.

The playground has smaller editing limits. These figures describe the API validator; a model may have its own context limits.

Laya API access

Use laya-english or laya-multilingual with the same POST /api/v1/systemone endpoint and your Jev AI Bearer key. Both support noul, choice and score, including saved-judge requests. Check GET /api/v1/models before sending a request.

curl --fail-with-body https://jev-ai.pro/api/v1/systemone -H "Authorization: Bearer $JEV_AI_API_KEY" -H "Content-Type: application/json" -d '{"model":"laya-english","state":"My payment failed.","questions":{"billing":{"type":"noul","instructions":"Is this about billing?"}}}'

For multilingual input, change the model to laya-multilingual. English accepts 512 total tokens per question; Multilingual accepts 1,024. This includes state, instructions, labels and framing. Each label is limited to 48 tokens, with additional question-and-label limits. Oversized input returns 422 without a charge and is never silently truncated.

Usage counts the input sequence for each question, including repeated state. Output usage is zero. Jev account billing applies: a 2× token rate, then 2 credits for the entire request if tokens are insufficient. Unconnected models return 503 before credits are reserved.

Explore Laya models · Create a Jev API key · Try Laya English

GPT-6 Luna API access

GPT-6 Luna is the model behind OpenAI’s Decisions API. It takes the same request as Jev: set model to gpt-6-luna on POST /api/v1/systemone, or to openai/gpt-6-luna on the Decisions-compatible POST /api/alpha/decisions. All three question types and saved judges work unchanged, and you can add an images array of up to 4 embedded PNG, JPEG or WebP images, as with Clef.

Jev AI forwards the request to OpenAI and never answers it with another model. If OpenAI is unavailable or declines a question, the request fails before any charge. Billing uses GPT-6 Luna’s model rate: input tokens × the multiplier on the API, or the model’s credit charge when tokens are insufficient.

GPT-6 Luna model guide · Try it in the playground

Mercury Decide API access

Mercury Decide, Inception’s decision model, uses the same request as Jev. Set model to mercury-decide on POST /api/v1/systemone, or to inception/mercury-decide on the Decisions-compatible POST /api/alpha/decisions. Saved judges and all three question types work unchanged.

Each request accepts up to 32,768 tokens. Longer input is rejected without a charge. Billing matches Jev: paid input tokens first, then one credit for the entire request if tokens are insufficient. If Mercury Decide is unavailable the request fails before any charge; it is never answered by another model.

Mercury Decide model guide · Jev vs Mercury Decide · Try it in the playground

List available models

Call GET /api/v1/models with the same Jev Bearer key. The response has a models array of name and description objects. It may include connected Laya models as well as Jev aliases, so use this endpoint to populate a selector instead of assuming every model is connected.

curl https://jev-ai.pro/api/v1/models \
  -H "Authorization: Bearer $JEV_AI_API_KEY"

The endpoint does not run inference. Keep using a Jev AI key even when a listed model has a Laya name.

Errors and retries

Disable automatic SDK retries of decision requests, as in the example above. A timeout or lost connection can leave the outcome uncertain; check your API usage and request status before sending another POST. Honor Retry-After for rate limits and use bounded retries only after a confirmed failure.

Saved judges

Use a saved judge when your application must run the same question set repeatedly. Send judgeId instead of questions; an optional revision rejects a stale definition with HTTP 409.

{
  "judgeId": "YOUR_SAVED_JUDGE_ID",
  "revision": 1,
  "state": "New text to evaluate"
}

Successful saved-judge calls include X-Jev-Judge-Id and X-Jev-Judge-Revision. Create and revise judges in My judges; its browser session routes are separate from the Bearer-key API. Use Batch to process files in the app.

Web context API

POST /api/v1/web-context compares a yes/no decision with and without source evidence. It accepts a Jev Bearer key and JSON. Without sources, Jev searches for the query (or the question when omitted). Pass sources to evaluate evidence your application already has without a fresh search.

{
  "question": "Does the published report support the claim?",
  "query": "published report productivity claim",
  "num_results": 4,
  "attribution": false
}

{
  "question": "Does this source support the claim?",
  "sources": [
    {
      "title": "Research summary",
      "url": "https://example.org/report",
      "publishedDate": null,
      "highlights": [
        "The reported increase was 13%."
      ]
    }
  ]
}

The response includes decision, confidence, with_web, without_web, sources, source_weights, usage, and latency. A fresh search costs more than reusing supplied sources; inspect billing response headers for the settled amount. This route has a separate limit of 120 requests per minute per account.