Decision
Perceptron provides a typed-decision API. Decision models accept a rendered observation (state) and a set of typed questions, and return one probability distribution per question. Decision models do not generate natural language: each answer is a distribution over the question’s options plus a confidence.
Base URL
https://perceptron.cloud/api/v1Authentication
Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEYAvailable Models
curl https://perceptron.cloud/api/v1/decide/modelsEach model reports its context length, input/output modalities, and per-token pricing under pricing.decision. When model is omitted from a request, the default decision model is used.
Decide
POST /api/v1/decide
Answer a rendered observation with one or more typed questions. The response contains one answer per question.
Request
curl https://perceptron.cloud/api/v1/decide \
-H "Authorization: Bearer $PERCEPTRON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bartmoss/io-3.5-control",
"state": "You are in a 5x5 grid. Snake head at (2,2) heading east. Food at (3,2).",
"questions": [
{
"id": "move",
"kind": "Choice",
"instructions": "Select the next move.",
"options": [
{ "label": "up", "description": "Move north" },
{ "label": "down", "description": "Move south" },
{ "label": "left", "description": "Move west" },
{ "label": "right", "description": "Move east" }
]
}
]
}'| Field | Type | Required | Description |
|---|---|---|---|
model | string | no | Decision model ID from GET /api/v1/decide/models; omit to use the default decision model |
state | string | yes | Rendered observation text the model decides over |
questions | array | yes | Typed question objects (see below) |
seed | integer | no | Sampling seed; a fixed seed reproduces the same answers |
miners | boolean | no | Route the request through Perceptron’s peer compute network |
use_my_nodes | boolean | no | Run the request on your own registered nodes |
Each entry in questions is a typed question object:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Identifier echoed on the answer |
kind | string | yes | Question type: Choice, Score, or Noul |
instructions | string | yes | What the model is deciding |
options | array | yes | Answer options, each with a label and description |
kind selects how the question is answered:
| Kind | What it does |
|---|---|
Choice | A distribution over the listed options; the highest-probability option is label |
Score | A distribution over ordered levels; the expected level is score |
Noul | A yes/no question; requires exactly two options, and the answer exposes probability_true |
Response
{
"answers": [
{
"id": "move",
"kind": "Choice",
"distribution": [0.148, 0.399, 0.131, 0.322],
"label": 1,
"score": 1.626,
"probability_true": 0.0,
"confidence": 0.076
}
],
"latency_ms": 8138.77,
"seed": 7247637261937428621,
"usage": {
"prompt_tokens": 106,
"completion_tokens": 1,
"total_tokens": 107
}
}| Field | Type | Description |
|---|---|---|
id | string | The question’s id |
kind | string | The question’s kind |
distribution | array | Probability distribution over the question’s options, in order |
label | integer | Index of the highest-probability option |
score | number | Expected level for a Score question |
probability_true | number | P(second option) for a Noul question; 0.0 otherwise |
confidence | number | Normalized confidence in the distribution |
See the full reference at API Reference.
Pricing
Decision inference is billed per token (input + output) from your credits balance at the model’s decision rates. See the live rates at GET /api/v1/decide/models, and Billing for more details.
Mining
Decision requests can be served by Perceptron’s peer compute network. Include "miners": true in the request body to prefer a miner, or "use_my_nodes": true to run on your own registered nodes. See Mining.
Mined requests can also be steered: node pins one node id, miner pins one miner (any of that account’s nodes), and node_blacklist / miner_blacklist are arrays of ids to exclude. Ids are the public node_id / miner_id values from GET /api/mining/nodes. A pinned target that cannot serve the request fails rather than routing elsewhere, and responses report the serving target in usage.node_id / usage.miner_id.
Playground
The Perceptron app includes a decision Playground for interactive testing without writing any code: open the app, open a decision model, and select Playground.