FreeJev logoFreeJev
Login
Back to home

One Jev API. Your preferred way to call it.

Sign in, create a FreeJev key, and send the same judgment from your application, terminal or Agent. All entry points share your account credits.

HTTP API

POST /api/v1/decisions with your key in the Authorization header. Set FREEJEV_API_KEY in your secret environment. This example contains fictional text.

curl 'https://freejev.org/api/v1/decisions' \
  -H "Authorization: Bearer $FREEJEV_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "state": "Since yesterday, every CSV export from our dashboard has stopped halfway through. I have retried three times and still cannot get the full report. Our customer review is this afternoon. Can someone help us get the export working before then?",
  "questions": {
    "judgment": {
      "instructions": "Which team should handle this support ticket?",
      "type": "choice",
      "criteria": {
        "Billing": "Invoices, payments, subscriptions, or refunds.",
        "Technical": "Errors or product features that are not working.",
        "Account": "Login, access, or account settings."
      }
    }
  }
}
JSON

model is accepted but ignored; the response model identifies the model actually used. state accepts text or JSON. questions maps your question IDs to definitions. A single request can answer up to 16 questions about the same input. Maximum JSON size: 128 KB; the upstream model context limit also applies.

  • choice: instructions plus a criteria object mapping answer labels to descriptions.
  • noul: a Yes/No question. The returned noul is the probability of Yes, from 0 to 1.
  • score: an ordered criteria array of 2–10 descriptions. The result is a weighted zero-based score, including decimals.

Responses contain request_id, model, answers and usage. Usage includes input/output tokens, credits used, credits waived on the last call, and remaining credits. GET /api/v1/usage reads your balance and the latest 50 call records.

Remote MCP, CLI installation, skill and connection management

CLI

The client source package includes the CLI and MCP server. It is not yet published to npm. From packages/freejev-client in the source checkout:

npm pack
npm install -g ./freejev-client-0.2.0.tgz
freejev --help

# Export judgment-config.json from the playground.
freejev decide --config judgment-config.json --file input.txt
cat input.txt | freejev decide --config judgment-config.json
freejev usage

For local testing, set FREEJEV_BASE_URL=http://127.0.0.1:4347. Successful output is JSON; errors go to stderr with a nonzero exit code. The client does not automatically retry billable requests.

Local MCP

Configure your Agent client to start freejev mcp over stdio. Pass your key through the client’s secret environment. If using the source checkout, replace the command with node and supply the absolute path to bin/freejev.mjs before mcp.

{
  "mcpServers": {
    "freejev": {
      "command": "freejev",
      "args": [
        "mcp"
      ],
      "env": {
        "FREEJEV_API_KEY": "<your FreeJev key>"
      }
    }
  }
}

The tools are jev_decide and freejev_usage. The local program connects to the API; inference is not performed on your computer.

Agent skill

Copy the client package’s skill/ folder into your Agent’s skill directory as freejev/. It explains question types, credit usage and retry handling. Install the CLI or configure MCP separately; a skill does not contain credentials.

Credits and errors

1 credit = 1,000 actual input tokens, including questions and criteria. Fractional usage is charged exactly; output tokens are free. You receive 10,000 one-time signup credits. Purchased credits never expire. Calls with no valid result do not consume user credits.

Each account runs one request at a time, up to 30 requests per minute. A positive balance admits the next request; FreeJev covers any small excess on the last call and leaves the balance at zero.

  • 400/413: fix the request or shorten the input.
  • 401/403: sign in, verify your email, or check your key.
  • 402: buy credits to continue.
  • 409: request already seen or another call is running.
  • 429: wait for the current rate window.
  • 503: the upstream is temporarily busy; follow Retry-After before retrying. Credits are not charged.
  • 502/504: upstream failure or timeout; no valid result, no user charge.

Send a unique Idempotency-Key for each intended run. Reusing it returns a conflict without a second charge. After a lost connection, check usage before running again. Results are not stored for replay; a new request ID can incur a new charge.

Data and interpretation

FreeJev records usage and billing metadata, not your input or response history. ZenMux and TypeSafe process inference remotely. Avoid secrets and sensitive customer data. Probabilities are judgments, not correctness guarantees; Jev does not generate reasoning explanations.