docs
// API Reference

System 1 Decisions

Typed decisions in one forward pass. Send a state and a map of named questions -- choice, score, noul -- and get one answer per question with its probabilities. POST /v1/systemone is TypeSafe's Jev API, served by open Laya-format models on Erebine Inference Microservices (EIMs) that run the Laya engine. The TypeSafe SDK works once base_url and model point here.

route
POST /v1/systemone
protocol
TypeSafe Jev
task mode
systemone
billed
input tokens

Overview

A System 1 model answers typed questions about a state and never generates text. The state is a string, a JSON object, or a JSON array: a support ticket, a record, a conversation, the current state of your application. You name each question; its answer comes back under the same name, with a probability for every option and, for choice and score, a confidence between 0 and 1.

Type Asks Answers with
choice Pick one option from a set you define. The chosen option, a probability per option, a confidence.
score Rate the state against ordered levels. The probability-weighted level (it can land between levels), a probability per level, a legend, a confidence.
noul A yes/no question. The probability that the answer is yes.

Extension outside the OpenAI specification. /v1/systemone reimplements TypeSafe's Jev API the way /v1/rerank follows Cohere's. The OpenAI SDKs have no method for it. Call it with the TypeSafe SDK, any Jev client, or plain HTTP.

It is served by endpoints whose task_mode is systemone, backed by a Laya-format model on an EIM running the Laya engine. See Deploying a Model.

Endpoint

POST /:project_id/:endpoint_slug/v1/systemone

The endpoint-scoped route answers with the model its endpoint serves. The direct dispatch twin takes the model from the body instead of the path:

POST /:project_id/:workspace_id/_direct/v1/systemone

curl
curl -X POST https://api.erebine.ai/proj_ABC123/my-decisions/v1/systemone \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "laya-bundle", "state": "Help! My payouts have been failing for 3 days.", "questions": { "department": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations", "sales": "Pricing, upgrades, new accounts" } }, "frustration": { "type": "score", "instructions": "How frustrated is the customer?", "criteria": ["Calm", "Frustrated", "Very angry"] }, "is_urgent": { "type": "noul", "instructions": "Does this convey urgency?", "criteria": { "true": "Explicitly time-sensitive", "false": "No urgency expressed" } } } }'

Request

The body is forwarded to the model byte for byte: key order, number text, and escapes reach it exactly as you sent them, so question ids and option names in any language and any escape form come back unchanged. Top-level fields not listed here are ignored.

Parameter Type Description
modelrequired string On the endpoint route, the model the endpoint serves, by name or id as GET /v1/models publishes them; surrounding whitespace and letter case are ignored. On _direct, the namespaced id of a System 1 deployment. Any other value, TypeSafe's jev-latest included, answers 404 model_not_found (see Errors and Retries). The response echoes the value you sent; it names a deployment and never selects a checkpoint inside one.
staterequired string | object | array What the questions are about. Not null. An array is read as a conversation.
questionsrequired object A map of question id to question. Up to 64 entries. An empty object is accepted, answers with an empty answers, and costs nothing.
max_lenoptional integer Extension. Tokens per question row, state included, from 1 to the deployment's context length. See Long Documents.
head_max_lenoptional integer Extension. Tokens per row reserved for the question and its options, from 1 to the deployment's context length. Each checkpoint sets its own default: 192 for Laya's English checkpoint, 256 for the multilingual one.

Question Types

Every question carries type and instructions. instructions is a string, an object, or an array: put the question in one field and the data it refers to in others, and name those fields in backticks.

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

choice

criteria is required: an object of option to description, where a description is a string, an object, an array, or null. From 1 to 100 options (Jev allows 255). A list of unique, non-empty option names is accepted as well; the TypeSafe SDK always sends the object form.

"department": { "type": "choice", "instructions": "Which team should handle this?", "criteria": { "billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations", "sales": null } }

score

criteria is required: an ordered array of 2 to 10 level descriptions, none of them null. Level 0 is the first.

"frustration": { "type": "score", "instructions": "How frustrated is the customer?", "criteria": ["Calm", "Frustrated", "Very angry"] }

noul

criteria is optional: an object with only the keys true and false, describing what a yes and a no mean. labels is an optional extension passed to the model unchanged.

"is_urgent": { "type": "noul", "instructions": "Does this convey urgency?", "criteria": { "true": "Explicitly time-sensitive", "false": "No urgency expressed" } }

Response

Response

{ "model": "laya-bundle", "answers": { "department": { "type": "choice", "choice": "billing", "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 }, "confidence": 0.81 }, "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 }, "is_urgent": { "type": "noul", "noul": 0.95 } }, "usage": { "input_tokens": 142, "output_tokens": 0 } }
Field Type Description
model string The model value you sent.
answers object One answer per question, keyed by your question ids, each with a type matching its question.
answers.<id>.choice string choice answers: the most probable option, spelled as in criteria.
answers.<id>.score number score answers: the probability-weighted level, from 0 to the last level; legend maps each level number back to its description.
answers.<id>.probabilities object choice and score answers: every option or level mapped to its probability; they sum to 1.
answers.<id>.confidence number choice and score answers: how certain the model is, from 0 to 1, derived from the probabilities.
answers.<id>.noul number noul answers: the probability of yes, from 0 to 1.
usage.input_tokens integer Tokens the model read. This is the billed quantity; see Billing.
usage.output_tokens integer Reported by the model. Not billed.

Laya-format models add fields Jev does not define: answer_confidence and action on answers, confidence on noul answers, and options in usage. They are additive; the TypeSafe SDK ignores them, and so can you. Nothing streams.

Limits

Limit Value Over the limit
Request body 2 MiB (2,097,152 bytes) of valid JSON, no duplicate key in any object, no escaped lone surrogate such as \ud800, nested at most 64 levels deep 422
Questions per request 64 422, param: "questions"
Options per choice 1 to 100 (Jev allows 255) 422, param: "questions.<id>.criteria"
Levels per score 2 to 10 422, param: "questions.<id>.criteria"
Options across all questions 512 choice options and score levels in total 422, param: "questions"
state 50,000 Unicode scalars for a string; 50,000 Unicode scalars of compact JSON for an object or array 422, param: "state"
max_len, head_max_len An integer from 1 to the deployment's context length 422, param names the field
Context length 512 to 8,192 tokens per question row, set per model Input past it is truncated; see Long Documents
Request size on a CPU deployment 24,576 estimated input tokens by default; the EIM's operator can change it, and can set one on a GPU deployment too 422, request too large for this deployment: about <n> tokens, limit <m>

The model applies its own count to an object or array state, which reads longer than compact JSON. A structured state close to 50,000 scalars can pass the router and still be refused by the model with 422.

Long Documents

Each question is read as its own row: the state, then the question and its options. A row holds at most the deployment's context length in tokens: the model's context_length, or the window its engine started with when that is smaller (served_context_length, see Model Management). Upload records context_length from the checkpoint: 512 for Laya's English checkpoint, and 1,024 for the multilingual one and for the bundle, which takes its multilingual checkpoint's. A System 1 model takes 512 to 8,192. Raise it on the model page, with PATCH /v1/models/{id} {"context_length": 8192}, or with erectl models update <id> --context-length 8192. Through the API the change needs a key with the management scope, and saving it restarts the engine on every endpoint serving the model (see Update Model Metadata).

  • Truncation. Input past the row's limit is cut. An array state (a conversation) loses its earliest items first; any other state loses its end. usage.input_tokens shows what was read.
  • Per request. max_len asks for a shorter or longer row, up to the context length. When you omit it, the checkpoint that answers reads its full row: the deployment's context length, or 512 on the bundle's English checkpoint.
  • Bundles. A deployment of the Laya bundle loads its English and multilingual checkpoints. English text goes to the English checkpoint, whose own limit stays 512; a state that does not fit it, or a max_len above it, is answered by the multilingual checkpoint instead. Non-English text goes to the multilingual checkpoint.
  • Single checkpoints. A deployment of one checkpoint, a fine-tune for example, answers every request with that checkpoint, in any language.
  • Accuracy. Laya documents 8,192 tokens for its multilingual checkpoint. Accuracy on long English input is yours to measure on your data.
  • Short inputs. A larger limit does not change answers for inputs that already fit, and speed follows the real input length.

Billing

A System 1 request is billed on usage.input_tokens at the endpoint's per-token rate (see Usage and Billing). Answers are not billed.

  • The state is counted once per question. Every question is its own row carrying the state, so input_tokens is the sum over questions of the state plus that question and its options, each row capped at the context length. Jev counts the state once, so the same multi-question request reports more input tokens here. Asking ten questions in one request still costs the same tokens as ten one-question requests, in one round trip.
  • Free outcomes. A busy engine or a model still loading (529 and 503, or 429 on _direct), an invalid request (422), an engine error (500), a lost connection to the EIM or its engine (503), and every refusal before the router dispatches the request are not charged. They still appear in your request logs.
  • Timeouts and disconnects. The engine cannot stop a forward pass once it starts. A request that times out (408), or whose client disconnects after the router dispatched it, is charged at its estimate: the sum over questions of the state plus the question, estimated from character counts, each capped at the context length.
  • A 408 the engine never ran. Some timeouts are charged at the estimate although the engine never started the request: one that waited at the EIM while the model loaded until its deadline passed, and one that reached the EIM after its deadline had already passed.
  • CPU deployments. A CPU deployment refuses, with 422, a request estimated above its limit (24,576 tokens by default). The limit is sized so a request it accepts finishes inside the 240 seconds the EIM waits for an answer, instead of timing out and being charged; a shorter tier request timeout, such as Free's 30 seconds, still applies.

Before dispatch the router reserves credit for the estimate and settles it on the reported count, or releases it for a free outcome.

Errors and Retries

Errors use the standard error body. A validation failure names the offending path in param:

{ "error": { "message": "A choice question takes at most 100 options, got 101.", "type": "invalid_request_error", "param": "questions.department.criteria", "code": "invalid_request" } }

A failure of the body as a whole -- over 2 MiB, not valid JSON, nested too deep -- carries no param. The endpoint route checks the body before its model, so an invalid body answers 422 whatever model it names. The endpoint route answers:

Status Type or code When
400 endpoint_task_mode_mismatch The endpoint's task mode is not systemone.
401 authentication_error Missing or invalid API key.
402 insufficient_quota A paid project's credit balance does not cover the request's estimate. Not charged.
403 access_denied The API key's IP filter refuses the client IP, or the path names a project that is not the key's own.
403 endpoint_restricted The key is restricted to another endpoint.
404 endpoint_not_found No endpoint with this slug in the project.
404 model_not_found The model in the body is not the model this endpoint serves, TypeSafe's jev-latest included. The body is the one the OpenAI API sends for a model you cannot use: the message names the value sent and param is null.
408 timeout No answer within the time limit: the endpoint tier's request timeout (30 seconds on Free; see Service Tiers), or 240 seconds once the engine has the request, whichever comes first. Charged at its estimate; see Billing.
422 invalid_request_error The body failed a rule under Limits, is not valid JSON, asks for max_len or head_max_len above the context length, exceeds the deployment's request size limit, or was refused by the model itself.
429 rate_limit_exceeded A request rate limit for this API key on this endpoint, or the key's own quota, was reached. Retry after Retry-After.
429 token_rate_limit_exceeded The project's tokens-per-minute budget is spent (see Rate Limits). Retry after Retry-After, 60 seconds.
500 internal_error The model failed while answering. Not charged.
501 backend_unavailable The router has no model storage configured: a fault in the deployment, not in the request.
503 model_provisioning The model is loading. Retry after Retry-After.
503 backend_unavailable No EIM the endpoint is bound to can take traffic, or the connection to the EIM or the EIM's engine failed mid-request. Not charged.
503 capacity_exceeded No EIM is available for the endpoint, or its EIM is unhealthy. Retry after Retry-After.
503 endpoint_inactive The endpoint is not active. It may be provisioning or disabled.
504 timeout The router found no EIM before its routing deadline. Retry after Retry-After.
529 overloaded_error, code capacity_exceeded The engine is busy or no EIM has room. Retry after Retry-After.

On _direct the router admits the request first. A body with no usable model, one that is not JSON included, is 400 invalid_request with param: "model"; a body over 2 MiB is 422; a project that is not the key's own is 403; and a model that is not a System 1 deployment in this project -- the TypeSafe SDK's default jev-latest included -- is 404 model_not_found. Load answers 429 with Retry-After: capacity_exceeded for a busy engine, a model that is still loading, or no EIM that can take the request, and listing_concurrency_exceeded when the model already has its published concurrency in flight. A routing timeout is 504 timeout. 503 means the service is unavailable, or the connection to the EIM or its engine failed. A client IP the key's filter refuses is 403 here too, and 402, 408, 422, and 500 mean what they mean on the endpoint route. See Direct Model Dispatch.

Retry 529, 429, and 503 with exponential backoff, honoring Retry-After. Do not retry a 408 or a client timeout: a 408 is charged at its estimate, and a retry runs the work again and is charged again. The TypeSafe SDK's default policy retries 408, 429, every 5xx, and its own timeouts; the example's RetryPolicy drops 408 and timeouts.

TypeSafe SDK

The TypeSafe Python SDK calls base_url plus /v1/systemone. Point it at the endpoint without /v1, set model, and raise the timeout:

bash
pip install typesafe-sdk
Python
from typesafe_sdk import Choice, Noul, RetryPolicy, Score, TypeSafeClient client = TypeSafeClient( api_key="ere_myproject_your_api_key", base_url="https://api.erebine.ai/proj_ABC123/my-decisions", model="laya-bundle", timeout=250.0, retry=RetryPolicy(http_statuses={429, *range(500, 600)}, api_timeout_error=False), ) response = client.system_one( "Help! My payouts have been failing for 3 days.", { "department": Choice( instructions="Which team should handle this?", criteria={ "billing": "Payments, invoicing, refunds", "technical": "Bugs, outages, integrations", "sales": "Pricing, upgrades, new accounts", }, ), "frustration": Score( instructions="How frustrated is the customer?", criteria=["Calm", "Frustrated", "Very angry"], ), "is_urgent": Noul(instructions="Does this convey urgency?"), }, ) print(response.choices["department"].choice) print(response.scores["frustration"].score) print(response.nouls["is_urgent"].noul)

The same settings from the environment:

bash
export TYPESAFE_API_KEY=ere_myproject_your_api_key export TYPESAFE_BASE_URL=https://api.erebine.ai/proj_ABC123/my-decisions export TYPESAFE_DEFAULT_MODEL=laya-bundle
  • model is required here. The SDK's default, jev-latest, names TypeSafe's model and does not exist on this router: it answers 404 model_not_found.
  • timeout=250.0. The SDK's default is 10 seconds. A long document on a CPU deployment takes longer than that, and a request the SDK abandons still runs on the engine and is charged at its estimate. 250 seconds sits above the 240 seconds the engine has once it has the request. A request that first waits for its model to load can take longer, up to the endpoint tier's request timeout; if your engines restart often, set the timeout above that.
  • RetryPolicy(http_statuses={429, *range(500, 600)}, api_timeout_error=False). The SDK's default policy also retries a 408 and its own timeouts, and each such retry runs the request again and is charged again. This policy drops both and keeps the retries for 429 and every 5xx, which are not charged. It also keeps the SDK's retry of a connection error: a refused connection costs nothing, but a connection that drops after the router dispatched the request is charged at its estimate, and the retry is charged again. Add api_connection_error=False to rule that out.
  • _direct. Use base_url="https://api.erebine.ai/proj_ABC123/ws_abc123/_direct" and the namespaced model id, for example model="erebine/laya-bundle".
  • Extensions. Pass max_len and head_max_len with extra_body={"max_len": 4096}.
  • client.models.list() is not supported. It expects TypeSafe's model list shape; this router's GET /v1/models answers in the OpenAI shape. List models with an OpenAI client or curl.

Code Examples

Substitute your project external id, endpoint slug, an API key from your project, and the model your endpoint serves.

Structured state (Python)

Python
import httpx BASE_URL = "https://api.erebine.ai/proj_ABC123/my-decisions/v1" API_KEY = "ere_myproject_your_api_key" response = httpx.post( f"{BASE_URL}/systemone", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "model": "laya-bundle", "state": {"ticket": "Help! My payouts have been failing for 3 days.", "plan": "pro"}, "questions": { "is_urgent": {"type": "noul", "instructions": "Does this convey urgency?"}, }, }, timeout=250.0, ) response.raise_for_status() answer = response.json()["answers"]["is_urgent"] print(f"P(urgent) = {answer['noul']:.2f}")

Conversation state (Node.js)

Node.js
const BASE_URL = "https://api.erebine.ai/proj_ABC123/my-decisions/v1"; const API_KEY = "ere_myproject_your_api_key"; const response = await fetch(`${BASE_URL}/systemone`, { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "laya-bundle", state: [ { role: "customer", text: "My payouts have been failing for 3 days." }, { role: "agent", text: "Sorry about that. Checking now." }, { role: "customer", text: "This is the third time this month." }, ], questions: { next_step: { type: "choice", instructions: "What should happen next?", criteria: { resolve: null, escalate: "Hand to a senior agent", refund: null }, }, }, }), signal: AbortSignal.timeout(250000), }); if (!response.ok) { const error = await response.json(); throw new Error(`systemone failed: ${error.error.message}`); } const data = await response.json(); console.log(data.answers.next_step.choice, data.answers.next_step.confidence);

Non-English text (curl)

Send text in any language raw or as JSON escapes; question ids may be non-ASCII too and come back exactly as sent.

curl
curl -X POST https://api.erebine.ai/proj_ABC123/my-decisions/v1/systemone \ -H "Authorization: Bearer ere_myproject_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "model": "laya-bundle", "state": "\u092e\u0947\u0930\u093e \u092d\u0941\u0917\u0924\u093e\u0928 \u0935\u093f\u092b\u0932 \u0939\u0948", "questions": { "is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" } } }'

Batch

/v1/systemone is a Batch API target. Each line's body reaches the model byte for byte and is billed like a synchronous request; a line answered 529 is requeued, and a line answered 422 fails. A System 1 engine computes one request at a time, so run bulk jobs on their own endpoint with its own EIM.

Deploying a Model

  1. A model. Any Laya-format checkpoint: a directory holding rl_agent_config.json, model.safetensors, tokenizer/, and encoder/config.json. The convaiinnovations/laya bundle is the English checkpoint at the root plus multilingual/, which is loaded, and typed-decisions/, which is accepted but not loaded; upload that folder as its own model to serve it. Upload it like any model (Model Upload). Upload records the engine as laya, the system_one capability, and the context length.
  2. An EIM running the Laya engine. The eim-laya-cpu, eim-laya-cuda, or eim-laya-rocm image (Laya Images), or the macOS app with Laya selected (Inference Engine).
  3. An endpoint. Choose the System 1 decisions task mode in the dashboard, or send task_mode: "systemone". Creating one needs an active EIM the endpoint's tier places on (on a self-hosted tier, one of your project's own) that runs the Laya engine, and binding a Laya model to an EIM running another engine is refused with 422. Quantization override, KV cache dtype, workload profile, and speculative decoding must be empty or auto; any other value is refused with 400. The model page and the model API refuse vLLM launch settings on a System 1 model: quantization, the parsers, speculative decoding, and the other vLLM-only settings.

Image Prompt Screening

Image generation on a shared endpoint screens every prompt on a System 1 endpoint in your own project before any image is made. Only a System 1 endpoint serving an approved screening model screens. A shared image generation endpoint cannot be created without an active one in the project (screening_endpoint_required), and the project's last active one cannot be deleted, suspended or moved to another task mode while a shared image generation endpoint uses it (screening_endpoint_in_use). Image generation on your own EIMs (a self-hosted tier) is not screened and needs none.

  • Approved models. The platform approves the System 1 models that may screen; when it offers exactly one System 1 model, that model is approved automatically. On the new-endpoint page, a System 1 model card that reads "Approved for image prompt screening" is one; deploy it as a System 1 endpoint. While no model is approved, shared image generation is unavailable.
  • Which endpoint. The Prompt screening choice on the workspace's Image generation card, else the project's first active System 1 endpoint serving an approved screening model. The choice lists only those endpoints.
  • Billing. Each screening is an ordinary System 1 request, billed on its input tokens and listed in your request logs. A prompt longer than the model reads in one row is screened in parts, one request each.
  • What is read. The prompt only. Images sent to /v1/images/edits, and reference images passed to the image tools, are not classified.
  • Refused. A prompt the screen refuses answers 400 with type image_generation_user_error and code moderation_blocked, as the OpenAI Images API does. No image is made, and the image is not billed.
  • Fails closed. With no usable System 1 endpoint serving an approved screening model, or with none approved at all, the request answers 400 screening_endpoint_required, and the message says which. When screening does not answer (no capacity, an engine error, an unreadable answer, or no answer within 15 seconds at most), it answers 503 screening_unavailable (429 on direct dispatch); retry it.
  • Responses and chat. The image_generation tool on /v1/responses reports the same codes as the failed image_generation_call item's error. In chat, and for x_generate_image on every surface, the tool returns a plain result with no image and the assistant says why. The Images API lists the same codes.

Research Decisions

Optional. When a workspace has a System 1 endpoint for decisions, research turns in chat and on /v1/responses check their work on it at two points. With none, nothing changes.

  • Before researching. At the start of a new conversation, a request that does not say what it is about may get one clarifying question before any search, where the surface can ask one.
  • Before answering. When the sources found look thin, the turn runs one more round of searches for what is missing. When they look like they disagree, the answer states the disagreement and cites both sides. Each happens at most once a turn, and the chat shows a short line when it does.
  • Mockups. When a chat turn finishes a mockup with no broken links or missing files, it may check the mockup against the request once: each page, section or feature your request names is looked for in the mockup, and one more round adds any that seem missing. When nothing is missing and your request does not name your business, it may ask you for the name instead of inventing one, where the surface can ask. The chat shows a short line when it does, such as "adding the pricing page".
  • Which endpoint. The Decisions (System 1) choice on the workspace's Endpoints settings: Auto (the project's first active System 1 endpoint), a specific System 1 endpoint, or Off. Any System 1 endpoint works; it does not need to be approved for image screening.
  • Billing. Each check is an ordinary System 1 request, billed on its input tokens and listed in your request logs. A turn makes at most two.
  • Never blocks. A check that fails or does not answer in a few seconds is skipped, and the turn goes on as if it had not been asked.