Hoody Decide reference
Section titled “Hoody Decide reference”Lookup tables for Hoody Decide.
Request fields
Section titled “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). 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) |
| 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) |
hoody-decide is not a catalog entry, so /api/v1/ai/models does not list it.
Question types
Section titled “Question types”How to choose a type: 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
Section titled “Answers”- Every probability is between 0 and 1.
- For
choiceandscore, the probabilities may sum to anything within 0.02 of 1, because of rounding. - A
scoreapproximates the probability-weighted level index; it need not equal the weighted sum of the returned probabilities exactly. legendmaps each index back to its level description after image normalization. Image parts retain onlytype: "image_url"andimage_url: { "url": "..." }.
Image parts
Section titled “Image parts”How to send an image, the accepted formats and the size limits: 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
Section titled “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, gets400 invalid_decision_request. - The reason: read
error.message; it does not always name a field or the exact excess.
Limit refusals
Section titled “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 <text> and <seconds> standing for the message and the wait:
{ "error": { "type": "rate_limit_exceeded", "code": "decision_limit_reached", "message": "<text>", "limit": "per_day_tokens", "retry_after_seconds": <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
Section titled “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. |