Jev AI API Documentation: Quickstart & Reference

Quickstart

Validate one decision in the playground

The Playground is the fastest way to understand Jev’s inputs and outputs. Once the question is useful, create an API key and connect it to your product.

1. 1

   Open the playground

   Sign in, open the Jev AI playground, and enter a real piece of business state.

2. 2

   Prepare state

   Use text, a JSON object, or an array of text to provide the context the decision needs.

3. 3

   Add questions

   Choose choice, score, or noul. You can mix all three types in one request.

4. 4

   Connect your code

   Create an API key in your workspace and call the production endpoint with an SDK or REST.

Input

Give state the context the decision needs

State is the content every question reads. Use a string for a simple case; use a JSON object when the decision needs a ticket, order, and policy together.

Current input boundary: Jev accepts text, JSON objects, and arrays of text. Image, audio, and video inputs are not supported yet.

Question types

Compose decisions from small questions

Each question should ask one specific, well-scoped thing. Multiple questions are evaluated in parallel against the same state, so you do not need to chain calls just to split a decision.

{
  "type": "noul",
  "instructions": "Does this message convey urgency?",
  "criteria": {
    "true": "Explicitly needs immediate attention",
    "false": "No urgency expressed"
  }
}

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Output

What the response gives your code

result.answers uses the same question IDs you sent. Typed output guarantees the field shape, but your application should still set thresholds by risk and keep a human-review path where appropriate.

• answers: Choice returns the selected choice, probabilities, and confidence; Score returns score, legend, per-level probabilities, and confidence; Noul returns noul.
• usage: Includes input_tokens and output_tokens, and may include cost in USD.
• elapsedMs: Time from sending the request to receiving the result, including validation—not pure model inference time.

Probability and confidence are signals for automation, not a guarantee of business accuracy. Use higher thresholds or human review for high-risk actions.

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

API reference

Evaluate state and return structured answers

Full HTTP API reference: evaluate a state against typed questions and receive one structured answer for each question.

Authorization: Bearer <API_KEY>
Content-Type: application/json

curl -X POST https://jevaimodel.org/v1/systemone \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Help! My payouts have been failing for 3 days.",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this convey urgency?"
      }
    }
  }'

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

Keep your API key in a server-side environment variable. Never put it in browser code or commit it to your repository. This page includes the request fields, question types, response shape, error codes, and retry behavior.

Agent usage

Use Jev inside a coding agent

The Jev Agent Skill teaches Codex, Claude Code, Cursor, and other compatible agents how to call this API for bounded decisions while keeping execution and permissions in your application.

npx skills add jev-ai/jev-agent-skill

export JEV_API_KEY="sk_your_key_here"
export JEV_LANGUAGE="en-US"

Use the Jev Agent skill. Classify this support ticket into exactly one team: billing, technical, account, or sales. Return the selected team, probabilities, and confidence. Do not contact the customer or modify any ticket yet.

Ticket: I was charged twice for my annual plan and need a refund.

Use the Jev Agent skill before running this proposed tool call. Judge whether it is safe without human approval. Consider side effects, reversibility, scope, and policy. If risky or uncertain, do not execute it.

Tool: delete_customer_records
Arguments: {where: last_login < 2023-01-01}
Policy: destructive database operations require a backup and human approval.

Use the Jev Agent skill to choose one approved model for this task. Optimize for quality first, then context capacity and cost. Return the selected model, probabilities, and whether to escalate. Do not call any model yet.

Task: review a 100k-token customer dispute.
Candidates: fast-model (32k, low cost), reasoning-model (200k, high cost), fallback-model (128k, medium cost).

Use the Jev Agent skill to check whether the evidence is sufficient to publish this claim. Consider source quality, freshness, direct support, and contradictions. Return a yes probability and the missing verification work. Do not publish yet.

Claim: Our API reduced median processing time by 40%.
Evidence: an internal benchmark from last month with 120 cases; no production traffic data; an older report showing a 12% improvement.

Use the Jev Agent skill to review whether this task is complete. Return one of complete, verify_more, or incomplete. Consider the objective, files changed, tests run, known gaps, and target-environment verification.

Objective: add API-key authentication to the production endpoint.
Completed: added the Authorization check and API-key lookup.
Verification: unit tests pass; production request and rate-limit behavior were not tested.

Error handling

Errors and retries

The endpoint uses standard HTTP status codes with a JSON response describing the error.

When you receive a 429 or 529, retry with exponential backoff instead of sending the same request immediately. SDKs with their default retry policy can handle these retries automatically.