Move from Jev

A Jev client keeps working on POST /v1/systemone. Change the address, the API key and model, which names one of our models, such as kettei-core. The path, state and questions stay as they are. The model you name answers, and the response’s model names it.

Before and after

In these examples, JEV_BASE_URL is the base URL you call Jev on today.

import os
+import uuid
import httpx

+operation_key = str(uuid.uuid4())  # one per operation: send it again if you retry
response = httpx.post(
-    f"{os.environ['JEV_BASE_URL']}/v1/systemone",
+    "https://api.sqwish.ai/v1/systemone",
    headers={
-        "Authorization": f"Bearer {os.environ['JEV_API_KEY']}",
+        "Authorization": f"Bearer {os.environ['SQWISH_API_KEY']}",
+        "Idempotency-Key": operation_key,
    },
-    json={"state": state, "questions": questions, "model": "jev-latest"},
+    json={"state": state, "questions": questions, "model": "kettei-core"},
    timeout=40.0,
)
answers = response.raise_for_status().json()["answers"]

+const operationKey = crypto.randomUUID(); // one per operation: send it again if you retry
const response = await fetch(
-  `${process.env.JEV_BASE_URL}/v1/systemone`,
+  "https://api.sqwish.ai/v1/systemone",
  {
    method: "POST",
    headers: {
-      Authorization: `Bearer ${process.env.JEV_API_KEY}`,
+      Authorization: `Bearer ${process.env.SQWISH_API_KEY}`,
+      "Idempotency-Key": operationKey,
      "Content-Type": "application/json",
    },
-    body: JSON.stringify({ state, questions, model: "jev-latest" }),
+    body: JSON.stringify({ state, questions, model: "kettei-core" }),
  },
);
const { answers, model } = await response.json();

+ SQWISH_OPERATION_KEY=$(uuidgen)  # one per operation: send it again if you retry
- curl --fail-with-body "$JEV_BASE_URL/v1/systemone" \
-   -H "Authorization: Bearer $JEV_API_KEY" \
+ curl --fail-with-body https://api.sqwish.ai/v1/systemone \
+   -H "Authorization: Bearer $SQWISH_API_KEY" \
+   -H "Idempotency-Key: $SQWISH_OPERATION_KEY" \
    -H "Content-Type: application/json" \
-   -d '{"state":"Please refund the duplicate charge.","model":"jev-latest",
+   -d '{"state":"Please refund the duplicate charge.","model":"kettei-core",
      "questions":{"refund":{"type":"noul","instructions":"Is a refund requested?"}}}'

- base URL: <your Jev base URL>
+ base URL: https://api.sqwish.ai
- Authorization: Bearer <your Jev key>
+ Authorization: Bearer <your OneHot key>
+ Idempotency-Key: <one key per operation>
- model: jev-latest
+ model: kettei-core

answers.refund.noul is still the yes probability. choice still returns the winning option, probabilities and confidence. score still returns an expected level, a legend, probabilities and confidence. OneHot’s own Python and TypeScript clients send the same request with systemone(), and translate it with systemone_translate() (systemoneTranslate() in TypeScript). Python’s systemone() sends only state, questions and model, so it can’t send assets, and TypeScript’s input type has no assets either. With a client, put images in a content array or in image nodes (Images).

Migration checklist

Create a OneHot API key. In the console, create a key and store it as SQWISH_API_KEY. It is shown once.
Change the base URL. Point the client at https://api.sqwish.ai. The path stays POST /v1/systemone.
Swap the key. Send Authorization: Bearer with the OneHot key.
Keep the Jev body. state and questions stay as they are, with noul, choice and score.
Name one of our models. Set model to kettei-fat, kettei-chub or kettei-core. The model you name is the one that answers. When it can’t answer, the request fails with an error that says why. No other model answers instead.
Compare a sample before you switch. Send the same questions to Jev and to OneHot. Look at the answers and at confidence on your own labels.
Add an idempotency key if you retry. With a key, POST /v1/systemone keeps a successful answer for 24 hours, and a replay doesn’t run or charge again. After a lost reply, resend the same key and the same body. An organisation with zero data retention keeps no answer, so there a retry runs again and is charged again. See when to retry and after a lost response.
Move to native decisions when you want them. Actions and abstention are on POST /v1/decide. Translate once. Do not send questions to /v1/decide.

What differs

Area	What changes
Address and key	The host becomes `https://api.sqwish.ai`, and the bearer token becomes a OneHot key. The path stays `/v1/systemone`.
Model	`model` names one of our models, such as `kettei-core`. The answer’s `model` is that ID. A Jev model ID, such as `jev`, `jev-latest`, `jev-preview` or `jev-1.13.0`, still works: `kettei-core` answers it, and the answer’s `model` is `kettei-core`. `/v1/systemone` never falls back to another model.
Confidence	On `/v1/systemone`, `choice` confidence is `(n * p_top - 1) / (n - 1)`, which matches Jev 1.13. `score` confidence is close to Jev’s, but not identical. `noul` has no confidence field, as on Jev. Native `p_top` is a different number.
Questions in one request	The questions of one request can affect each other’s answers, and the state is paid for once. For an answer on its own, send that question in a request of its own.
Answer shape	`noul`, `choice` and `score` keep their fields. We also return `model`, usage and timing.
Retries	Both `/v1/systemone` and `/v1/decide` accept `Idempotency-Key`. Retry only when `error.retryable` is true, or when the reply never arrived.
Native decisions	`POST /v1/decide` uses `context` and `decisions`. It can abstain and name an action, and both are opt-in. Sending `questions` to `/v1/decide`, or `decisions` to `/v1/systemone`, returns an error that points at the right route. A request to `/v1/decide` with `questions` and no `decisions` gets `422 jev_request_shape`.
Images	`state` may hold images. `kettei-fat` and `kettei-chub` read them, and `kettei-core` reads text only. A multipart request, as Jev’s SDKs send, carries the files without base64. See Images.
Extra fields	Fields `/v1/systemone` doesn’t know are ignored. Five are refused, each with its own code. See Extra fields.

Shape compatibility is not a promise of the same accuracy or latency. Compare on your labels before you point production here.

Compare before you switch

Send one sample to both. Keep the Jev path until the comparison looks right. To price the sample first, POST /v1/systemone/estimate takes the same body and quotes it without running a model.

const ask = { state, questions };
const headers = { "Content-Type": "application/json" };
const [jev, onehot] = await Promise.all([
  fetch(`${process.env.JEV_BASE_URL}/v1/systemone`, {
    method: "POST",
    headers: { ...headers, Authorization: `Bearer ${process.env.JEV_API_KEY}` },
    body: JSON.stringify({ ...ask, model: "jev-latest" }),
  }).then((response) => response.json()),
  fetch("https://api.sqwish.ai/v1/systemone", {
    method: "POST",
    headers: { ...headers, Authorization: `Bearer ${process.env.SQWISH_API_KEY}` },
    body: JSON.stringify({ ...ask, model: "kettei-core" }),
  }).then((response) => response.json()),
]);
for (const id of Object.keys(questions)) console.log(id, jev.answers[id], onehot.answers[id]);

Translate when you want native decisions

POST /v1/systemone/translate returns the /v1/decide request and notes on what changed. It runs no model, costs nothing and needs no key.

curl --fail-with-body https://api.sqwish.ai/v1/systemone/translate \
  -H "Content-Type: application/json" \
  -d '{"model":"kettei-core","state":"Please refund the duplicate charge.",
    "questions":{"refund":{"type":"noul","instructions":"Is a refund requested?"}}}'

It returns:

{
  "request": {
    "model": "kettei-core",
    "context": "Please refund the duplicate charge.",
    "decisions": [{"id": "refund", "question": "Is a refund requested?", "kind": "binary"}]
  },
  "notes": ["Jev's noul answer is probabilities.yes here."]
}

Jev	Native OneHot
`state`	`context`
`questions` keyed by id	`decisions` with an `id` on each item
`instructions`	`question`
`noul`	`binary`. The yes probability is `probabilities.yes`.
`choice` criteria	`single` outcomes. A Jev confidence cutoff becomes `policy.abstain_below`. The translator states the formula.
`score` criteria	Ordered `ordinal` outcomes and a rubric. The level is `expected_level`.

Add abstention only after you have compared the translated request on your own labels. Preserve outcome order. Jev confidence is not native p_top, and neither is a measure of correctness. Translate refuses a choice option named abstain with 422 reserved_outcome, because OneHot keeps abstain for a decision that chooses not to answer. Rename the option, then translate again. Fields /v1/systemone doesn’t know are ignored, and five are refused (extra fields). A field from another provider’s API does not transfer on its own.

Images

/v1/systemone takes images inside state. kettei-fat and kettei-chub read them, and kettei-core reads text only. kettei-core answers a Jev model ID, so a request with images names kettei-fat or kettei-chub. The model reads exactly what the same request to /v1/decide shows it, and POST /v1/systemone/translate returns that request. Images are base64 JPEG, PNG or WebP: a data: URL in an image part, and plain base64 in a node or an asset. URLs are not fetched. Put images in state, because a top-level images field is refused. Shrink a larger picture to the size the model reads, and send a photo as JPEG. The limits, errors and billing are the ones on Images. usage gives images and image_tokens here too. A request carries images in one of three forms.

A content array

Send state as a list of text parts and image_url parts. The text parts, joined by spaces, are the context. An anchor such as <image:1> or <image:2> stands where each image is.

{"model": "kettei-chub",
 "state": [{"type": "text", "text": "Return request 4411. Photo of the item as received:"},
           {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}],
 "questions": {"damaged": {"type": "noul", "instructions": "Is the item damaged?"}}}

Image nodes

Put image nodes anywhere in an object or array state. Each node is read where it stands, as its anchor.

{"model": "kettei-chub",
 "state": {"photo": {"type": "image", "data": "<base64 of the file>", "mime": "image/jpeg"}},
 "questions": {"damaged": {"type": "noul", "instructions": "Is the item damaged?"}}}

An assets map

This is Jev’s own form. List each image once in a top-level assets map, under a reference you choose. Then write the reference in state where the image goes.

{"model": "kettei-chub",
 "state": {"photo": "7f3c1a9e-photo"},
 "assets": {"7f3c1a9e-photo": {"type": "image", "format": "jpg", "data_base64": "<base64 of the file>"}},
 "questions": {"damaged": {"type": "noul", "instructions": "Is the item in `photo` damaged?"}}}

A reference that is a value of an object or array state is read as an image node there.
References in a state that is one string are read as a content array of its text and images.
Each use of a reference is an image of its own. A request takes up to 8 images.
Each use is billed for the image’s tokens, so a reference used twice is billed twice. On /v1/decide, an image is billed once, however many times its anchor appears.
Choose references that can’t occur in your text by accident, such as a new UUID for each image.

The request is refused with invalid_request when a reference is used nowhere, or stands inside a longer string of an object or array state. A reference in a question is refused too: images go in state here.

Multipart requests

A multipart request carries each image’s file as it is, a quarter smaller than base64. Jev’s SDKs send one when a request has images. /v1/systemone takes it as multipart/form-data:

The first part is named request and holds the request’s JSON.
Each image’s file is in a part of its own. Its asset in assets names that part with "part": "<part name>".
Every part has a name of its own. Every part after request is the file of exactly one asset, with an image’s media type or none.

cat > request.json <<'JSON'
{"model": "kettei-chub",
 "state": {"photo": "7f3c1a9e-photo"},
 "assets": {"7f3c1a9e-photo": {"type": "image", "part": "photo-file"}},
 "questions": {"damaged": {"type": "noul", "instructions": "Is the item in `photo` damaged?"}}}
JSON
curl --fail-with-body https://api.sqwish.ai/v1/systemone \
  -H "Authorization: Bearer $SQWISH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'request=<request.json' \
  -F 'photo-file=@photo.jpg;type=image/jpeg'

POST /v1/systemone/estimate and POST /v1/systemone/translate take multipart requests too. A body that is not multipart data gets 400 invalid_multipart. A body that breaks these rules gets 422 invalid_request. Shrink each picture to fit here too.

Extra fields

/v1/systemone ignores fields it doesn’t know, at the top level and inside a question. So a client’s own additions change nothing. Sampling settings, metadata and a provider’s hints are examples. Five things are refused, each with its own code:

What you send	Code
A top-level `images` field	`images_in_state`
`stream` set to `true`	`stream_not_supported`
`n` other than `1`	`n_not_supported`
A native request’s `context` or `decisions`	`native_request_shape`
A likely misspelling of `state` or `assets`, or of a question’s `type`, `instructions` or `criteria`, sent without the field itself. `State` and `criterias` are examples.	`unknown_field`

With unknown_field, a typo is never answered as if the field were left out. Errors says what to do about each code.

Get started

Make decisions

Improve accuracy

Use the API

Account and billing

Privacy and security

Integrations