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/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Available Models

curl https://perceptron.cloud/api/v1/decide/models

Each 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" }
        ]
      }
    ]
  }'
FieldTypeRequiredDescription
modelstringnoDecision model ID from GET /api/v1/decide/models; omit to use the default decision model
statestringyesRendered observation text the model decides over
questionsarrayyesTyped question objects (see below)
seedintegernoSampling seed; a fixed seed reproduces the same answers
minersbooleannoRoute the request through Perceptron’s peer compute network
use_my_nodesbooleannoRun the request on your own registered nodes

Each entry in questions is a typed question object:

FieldTypeRequiredDescription
idstringyesIdentifier echoed on the answer
kindstringyesQuestion type: Choice, Score, or Noul
instructionsstringyesWhat the model is deciding
optionsarrayyesAnswer options, each with a label and description

kind selects how the question is answered:

KindWhat it does
ChoiceA distribution over the listed options; the highest-probability option is label
ScoreA distribution over ordered levels; the expected level is score
NoulA 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
  }
}
FieldTypeDescription
idstringThe question’s id
kindstringThe question’s kind
distributionarrayProbability distribution over the question’s options, in order
labelintegerIndex of the highest-probability option
scorenumberExpected level for a Score question
probability_truenumberP(second option) for a Noul question; 0.0 otherwise
confidencenumberNormalized 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.