> ## Documentation Index
> Fetch the complete documentation index at: https://docs.electronhub.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Decisions

> Get structured judgments your code can act on

Send the facts in `state` and the judgments you need in `questions`. The answer is a pick from a set, a score on a scale, or a yes/no measure. `state` is text or JSON. The model does not read images, and it does not write chat text.

`jev` is TypeSafe's decision model at \$0.042 per million input tokens. Output tokens are free. Requests count toward your normal rate limits.

## Create Decision

`POST /systemone`

`POST /decisions` is the same endpoint.

### Request Body

**model** `string` (default: jev)

`jev`. `jev-latest`, `typesafe/jev`, and `typesafe/jev-latest` are aliases. Version pins such as `typesafe/jev-1.13` are rejected because only the current Jev is served. Proxy keys must send `model`.

**state** `string | object | array` *required*

The facts needed to answer: the ticket, records, conversation, or policy. A string, object, or array, including an empty one. Numbers, booleans, and `null` are rejected. Image parts and data-URL images are rejected. See [Images](#images).

**questions** `object` *required*

A non-empty map of question IDs to question definitions. Answers use the same IDs. IDs must be non-empty and cannot be `__proto__`.

Each question has:

**questions.\{id}.type** `string` *required*

`choice`, `score`, or `noul`. Case-sensitive.

**questions.\{id}.instructions** `string | object | array` *required*

The question to answer. The question ID only labels the answer; it is not read as the question.

**questions.\{id}.criteria** `object | array`

What each option or level means. Required for `choice` and `score`, optional for `noul`. See [Question types](#question-types).

Every question sees the same `state`. Send independent questions together in one call and keep each one focused on a single judgment. The combined `state` and `questions` can be up to 32,000 tokens. Other body fields, such as `user`, `session_id`, or `assets`, are ignored.

### Images

Jev does not read image bytes. An image part in `state` (`image_url`, `image`, or `input_image`), or any `data:image/` URL, is rejected with `400` and `param` set to `state`. Describe the image with a vision model such as `gemini-2.5-flash`, then put that description in `state`.

```python theme={null}
auth = {"Authorization": "Bearer YOUR_API_KEY"}
text = requests.post("https://api.electronhub.ai/v1/chat/completions", headers=auth, json={
    "model": "gemini-2.5-flash",
    "messages": [{"role": "user", "content": [
        {"type": "text", "text": "Describe this image."},
        {"type": "image_url", "image_url": {"url": data_url}}]}],
}).json()["choices"][0]["message"]["content"]
answer = requests.post("https://api.electronhub.ai/v1/decisions", headers=auth, json={
    "model": "jev", "state": text,
    "questions": {"colour": {"type": "choice", "instructions": "Dominant colour?",
        "criteria": {"red": "red", "green": "green", "blue": "blue"}}}}).json()
```

A written description is ordinary text, including one stored under a field named `image`. There is no `box` question type. Ask a `choice`, `score`, or `noul` about the description.

### Question types

| Type | `criteria` | Answer fields |
| - | - | - |
| `choice` | Object of option ID to description. 1 to 255 options. | `choice`, `probabilities`, `confidence` |
| `score` | Array of level descriptions, lowest first. 1 to 10 levels. An object keyed `"0"`, `"1"`, ... with no gaps is also accepted. | `score`, `legend`, `probabilities`, `confidence` |
| `noul` | Optional. If sent, an object with both `true` and `false` keys and no others. | `noul` |

Descriptions may be strings, objects, or arrays, and may be empty. A `choice` description may also be `null`. Numbers and booleans are rejected.

### Reading answers

* `choice`: the selected option ID. `probabilities` maps every option ID to a probability.
* `score`: the expected level on the 0-based scale, as a decimal (for example `2.82` of 0 to 3). `legend` maps each level index to the description you sent. `probabilities` maps each level index to a probability.
* `noul`: the probability of yes, from 0 to 1. Near 0.5 means uncertain. There is no `confidence` field.
* `confidence`: a separate certainty signal from 0 to 1. It is not the largest probability and may be omitted; treat a missing value as unknown.

Probabilities are rounded to two decimals. Identical requests can differ by about 0.02, so compare against thresholds rather than exact values.

### Example

```bash cURL theme={null}
curl -X POST "https://api.electronhub.ai/v1/systemone" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev",
    "state": "My card was charged twice. Please help ASAP.",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payments and refunds",
          "technical": "Bugs and integrations",
          "sales": "Pricing and new accounts"
        }
      },
      "severity": {
        "type": "score",
        "instructions": "How severe is this request?",
        "criteria": [
          "No impact",
          "Minor inconvenience",
          "The customer is blocked",
          "Money or data is at risk"
        ]
      },
      "urgent": {
        "type": "noul",
        "instructions": "Does this need a response today?",
        "criteria": {
          "true": "The customer is blocked or money is at risk",
          "false": "It can wait"
        }
      }
    }
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api.electronhub.ai/v1/systemone', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'jev',
    state: 'My card was charged twice. Please help ASAP.',
    questions: {
      team: {
        type: 'choice',
        instructions: 'Which team should handle this?',
        criteria: {
          billing: 'Payments and refunds',
          technical: 'Bugs and integrations',
          sales: 'Pricing and new accounts'
        }
      }
    }
  })
});

const { answers } = await response.json();
console.log(answers.team.choice);
```

```python Python theme={null}
import requests

response = requests.post(
    'https://api.electronhub.ai/v1/systemone',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'jev',
        'state': 'My card was charged twice. Please help ASAP.',
        'questions': {
            'team': {
                'type': 'choice',
                'instructions': 'Which team should handle this?',
                'criteria': {
                    'billing': 'Payments and refunds',
                    'technical': 'Bugs and integrations',
                    'sales': 'Pricing and new accounts',
                },
            }
        },
    },
    timeout=60,
)

print(response.json()['answers']['team']['choice'])
```

### Response

```json theme={null}
{
  "id": "gen-dec-1791097042-2ZZZZefJjFbJsulpQa5T",
  "object": "decision",
  "model": "jev",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 1, "sales": 0, "technical": 0 },
      "confidence": 1
    },
    "severity": {
      "type": "score",
      "score": 2.82,
      "legend": {
        "0": "No impact",
        "1": "Minor inconvenience",
        "2": "The customer is blocked",
        "3": "Money or data is at risk"
      },
      "probabilities": { "0": 0, "1": 0.08, "2": 0.01, "3": 0.91 },
      "confidence": 0.82
    },
    "urgent": {
      "type": "noul",
      "noul": 0.88
    }
  },
  "usage": {
    "input_tokens": 434,
    "output_tokens": 68,
    "total_tokens": 502
  }
}
```

Read each answer by its question ID, then apply your own rules. Validate thresholds on your own examples.

```javascript theme={null}
const { team } = data.answers;

if ((team.confidence ?? 0) < 0.8) {
  queueForReview(ticket);
} else {
  routeTicket(ticket, team.choice);
}
```

## Describe the endpoint

`GET /systemone` (or `GET /decisions`) returns the default model (`jev`), its context length and price, the question types, and a `models` list with every decision model. No API key is needed. `jev` allows 32,000 tokens.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid body, such as a missing `instructions`, an unknown `type`, invalid `criteria`, or image content in `state`. `param` names the field. Also returned for a version-pinned or unsupported model, and when the request exceeds that model's context limit. |
| 401 | Missing or invalid API key. |
| 402 | Insufficient balance. |
| 429 | Your rate limit was reached, or the decision model is busy. Wait for `Retry-After` when present, then retry with backoff. |
| 503 | The decision model is temporarily unavailable. Retry with backoff. |

Failed requests are not charged.


## OpenAPI

````yaml POST /systemone
openapi: 3.0.1
info:
  title: Electron Hub API
  description: >-
    Unified API platform integrating 200+ AI models for chat, image generation,
    speech-to-text, embeddings, and more.
  version: 1.0.0
  contact:
    name: Electron Hub Support
    email: support@electronhub.ai
    url: https://discord.com/invite/electronhub
  license:
    name: MIT
servers:
  - url: https://api.electronhub.ai/v1
    description: Production API v1
security:
  - bearerAuth: []
paths:
  /systemone:
    post:
      summary: Create Decision
      description: >-
        Ask a decision model structured questions about `state`. The model is
        `jev` ($0.042 / 1M input). Output tokens are free. `state` is text or
        JSON. Image parts and data-URL images are rejected. `POST /decisions` is
        an alias. Unknown body fields are ignored.
      operationId: createDecision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    DecisionRequest:
      type: object
      required:
        - state
        - questions
      properties:
        model:
          type: string
          default: jev
          example: jev
          description: >-
            `jev`. `jev-latest`, `typesafe/jev`, and `typesafe/jev-latest` are
            aliases. Version pins are rejected.
        state:
          description: >-
            The facts needed to answer. A string, object, or array, including
            empty. Image parts (image_url, image, input_image) and data-URL
            images are rejected with param state. Describe the image with a
            vision model and put that text here.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
        questions:
          type: object
          description: >-
            Non-empty map of question IDs to question definitions. IDs must be
            non-empty and cannot be `__proto__`.
          additionalProperties:
            $ref: '#/components/schemas/DecisionQuestion'
          minProperties: 1
    DecisionResponse:
      type: object
      required:
        - id
        - object
        - model
        - answers
        - usage
      properties:
        id:
          type: string
        object:
          type: string
          example: decision
        model:
          type: string
          example: jev
        answers:
          type: object
          description: One answer per question ID.
          additionalProperties:
            $ref: '#/components/schemas/DecisionAnswer'
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            total_tokens:
              type: integer
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
    DecisionQuestion:
      type: object
      required:
        - type
        - instructions
      properties:
        type:
          type: string
          enum:
            - choice
            - score
            - noul
          description: Case-sensitive.
        instructions:
          description: The question to answer.
          oneOf:
            - type: string
            - type: object
            - type: array
              items: {}
        criteria:
          description: >-
            choice (required): object of option ID to description, 1 to 255
            options; a description may also be null. score (required): array of
            level descriptions, lowest first, 1 to 10 levels; an object keyed
            "0", "1", ... with no gaps is also accepted. noul (optional): object
            with exactly the keys `true` and `false`. Descriptions may be
            strings, objects, or arrays.
          oneOf:
            - type: object
              additionalProperties: {}
            - type: array
              minItems: 1
              maxItems: 10
              items: {}
    DecisionAnswer:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - choice
            - score
            - noul
        choice:
          type: string
          description: 'choice: the selected option ID.'
        score:
          type: number
          description: 'score: expected level on the 0-based scale, as a decimal.'
        legend:
          type: object
          additionalProperties: {}
          description: 'score: level index to the description sent in `criteria`.'
        noul:
          type: number
          minimum: 0
          maximum: 1
          description: 'noul: probability of yes. Near 0.5 is uncertain.'
        probabilities:
          type: object
          additionalProperties:
            type: number
          description: >-
            choice and score: option ID or level index to probability, rounded
            to two decimals.
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            choice and score: certainty signal. Not the largest probability. May
            be omitted.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your API key (starts with 'ek-')

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.