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" }
        ]
      }
    ]
  }'

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.