# Hoody Decide reference **Page:** foundation/hoody-ai/decisions/reference [Download Raw Markdown](./foundation/hoody-ai/decisions/reference.md) --- # Hoody Decide reference Lookup tables for [Hoody Decide](/foundation/hoody-ai/decisions/). ## Request fields `POST https://ai.hoody.com/api/v1/systemone` or `POST https://ai.hoody.com/api/v1/decisions`, with a JSON body. | Field | Rule | |---|---| | `model` | `hoody-ai/hoody-decide`, or the accepted aliases `hoody/hoody-decide` and `hoody-decide`. Responses always name it `hoody-ai/hoody-decide`. A request naming it is answered by a decision model Hoody chooses | | `state` | What the questions are about. A string, a JSON object, or a JSON array | | `questions` | An object mapping each question name (1 to 256 characters) to a question. Every name comes back as a key of `answers`. A request carries 1 to 64 questions | | `type` (per question) | `noul`, `choice` or `score` ([question types](#question-types)). The `box` type is not supported | | `instructions` (per question) | Required on every question. A string, object or array that says what to decide | | `criteria` (per question) | Depends on the type ([question types](#question-types)) | | Other top-level fields | Omit them: they do not control the decision, and some names are still validated and can cause a `400` response | | Repeated top-level fields | Do not repeat top-level field names ([`duplicate_root_key` and `invalid_decision_request`](#troubleshooting)) | `hoody-decide` is not a catalog entry, so `/api/v1/ai/models` does not list it. ## Question types How to choose a type: [Write the questions](/foundation/hoody-ai/decisions/#write-the-questions). | `type` | `criteria` | Answer fields | |---|---|---| | `noul` | Optional: an object with exactly `"true"` and `"false"`, each a string, object or array | `type: "noul"` and `noul`, the probability of yes from 0 to 1 | | `choice` | Required: an object of 1 to 255 non-empty labels, each mapped to a string, object, array or `null` description | `type: "choice"`, `choice` (a label with the highest probability), `confidence` from 0 to 1, and a `probabilities` object covering every label | | `score` | Required: an array of 2 to 10 level descriptions (string, object or array, never `null`), lowest first | `type: "score"`, `score` from 0 to the number of levels minus 1 (it may be fractional), `confidence` from 0 to 1, and `probabilities` and `legend` objects keyed `"0"`, `"1"`, and so on | ## Answers - Every probability is between 0 and 1. - For `choice` and `score`, the probabilities may sum to anything within 0.02 of 1, because of rounding. - A `score` approximates the probability-weighted level index; it need not equal the weighted sum of the returned probabilities exactly. - `legend` maps each index back to its level description after image normalization. Image parts retain only `type: "image_url"` and `image_url: { "url": "..." }`. ## Image parts How to send an image, the accepted formats and the size limits: [Send images in the state](/foundation/hoody-ai/decisions/#send-images-in-the-state). | Rule | Detail | |---|---| | What is read as an image part | Any object in `state`, at any depth, with a key named `image`, `image_url`, `input_image`, `file` or `file_data` (case-sensitive), or a `type` of `image`, `image_url`, `input_image`, `file` or `input_file` (case-insensitive) | | If it is not a valid image part | The request fails with `400 invalid_decision_request`, so a plain object such as `{ "file": "app.log" }` is refused. Rename such keys, or send the state as a string (for example the JSON text of the object) | | Strings that begin with `data:` | Strings beginning with `data:` after leading whitespace (case-insensitive) are accepted only as the URL inside a valid image part. Elsewhere in `state`, instructions or criteria descriptions, they cause `400 invalid_decision_request` | | Where else the rule applies | Question instructions and criteria descriptions (the `noul` and `choice` description values and the `score` levels) | | Where it does not apply | `choice` label names can be any non-empty string, including `file` or `image` | ## Size limits | What | Limit | |---|---| | Questions per request | 64 | | Labels per `choice` question | 255 | | Levels per `score` question | 2 to 10 | | Text in `state` (images not counted) | 128 KiB | | Images per request | 4, 1 MiB each, inline only | | Estimated input tokens per request | 32,000 | | Whole request body | 8 MiB | - **Token estimate:** it covers the state, the questions and the images, and the state can count more than once when you ask several questions, so a request can fit every byte limit and still be over the token limit. - **Over a limit:** a body over 8 MiB gets `413`; the response may be plain text without a JSON error code. Exceeding the other request limits, or using a shape the decision models cannot answer, gets `400 invalid_decision_request`. - **The reason:** read `error.message`; it does not always name a field or the exact excess. ## Limit refusals When a decision limit runs out, the request is refused with `429 decision_limit_reached` until it frees up. The body has this shape, with `` and `` standing for the message and the wait: ``` { "error": { "type": "rate_limit_exceeded", "code": "decision_limit_reached", "message": "", "limit": "per_day_tokens", "retry_after_seconds": , "reset_at": "2026-10-19T09:41:07Z" } } ``` | Field | Meaning | |---|---| | `limit` | The kind of limit reached: `per_minute_requests`, `per_day_requests`, `per_day_questions`, `per_day_tokens` or `concurrent` | | `message` | Text for people; branch on `code` and `limit` | | `retry_after_seconds` | The wait. The `Retry-After` header carries the same wait | | `reset_at` | That time in UTC | ## Troubleshooting The status and `code` say whether to change the request or wait and retry. | Status | `code` | Meaning | |---|---|---| | 400 | `invalid_body` | The body could not be accepted as a JSON request. Check its encoding, JSON syntax and field types, and omit extra top-level fields. | | 400 | `duplicate_root_key` | A model-selection field (`model`, `models`, `fallbacks` or `preset`) appears more than once. Remove the duplicate. | | 400 | `invalid_decision_request` | Decision validation failed, another top-level field is duplicated, a request limit was exceeded, or the AI service refused the request. Read `error.message` and revise the request. | | 400 | `decision_requires_computer` | Call it from inside a computer with the computer token. | | 400 | `decision_model_endpoint_unsupported` | The model was named on another endpoint. Use `POST /api/v1/systemone` or `POST /api/v1/decisions`. | | 413 | `invalid_decision_request` or no JSON code (plain-text response) | The body is over 8 MiB. | | 429 | `decision_limit_reached` | A decision limit of the computer's server is used up. Retry after `Retry-After`. | | 503 | `decision_capacity_exhausted` | Decisions are at capacity right now. Retry after `Retry-After`. | | 503 | `decision_routing_unavailable` | Decisions are unavailable right now. Retry after `Retry-After`. | | 503 | `free_owner_identity_missing` | Hoody could not tell which account owns the computer. Contact support if it persists. |