Penny decision API

Pocketsflow Penny 1 is a small open decision model (0.6B parameters). You give it a situation (the state) and one typed question; it answers with a calibrated confidence and tells you whether that confidence is high enough to act without a person (auto). Penny never writes text. Its answer is a single token, read from the model’s next-token probabilities, so every call is one fast forward pass and the probabilities themselves are the confidence. Read how it was trained and measured on the Penny research page. Base URL https://api.pocketsflow.com, API key in the Authorization header, like every other endpoint. Available on every plan.

Ask a question

curl https://api.pocketsflow.com/v1/penny/decide \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "state": {
      "order_id": "ord_123",
      "amount": 49.99,
      "reason": "Never received the file",
      "days_since_purchase": 3
    },
    "question": "What should we do with this refund request?",
    "type": "choice",
    "options": ["Refund in full", "Offer store credit", "Decline politely"]
  }'

{
  "model": "pocketsflow-penny-1",
  "type": "choice",
  "choice": "Refund in full",
  "index": 0,
  "confidence": 0.9112,
  "probs": [0.9112, 0.0701, 0.0187],
  "auto": true,
  "usage": { "free_remaining": 958, "credits_remaining": 0 }
}

Field	Required	Notes
`state`	yes	The situation: prose, an email, a table row, or any JSON object. An object is sent to the model as 2-space JSON. At most 8,000 characters (after that conversion).
`question`	yes	One question about the state, at most 500 characters.
`type`	yes	`choice`, `yes_no` or `score` (below).
`options`	`choice` only	2 to 8 options, one line and at most 120 characters each. Leave it out for `yes_no` and `score`.

The three question types

Type	Penny answers	Answer fields	`probs`
`choice`	One of your 2 to 8 `options`	`choice` (the option, exactly as you sent it) and `index` (0-based)	One per option, in your order
`yes_no`	Yes or no	`yes` (`true` or `false`)	`[yes, no]`
`score`	A number from 1 (lowest) to 5 (highest)	`score`: the expected score, two decimals (for example `3.93`)	Scores 1 to 5

For score, say in the question what 1 and 5 mean: "How likely is this payment to be fraud? 1 = very unlikely, 5 = very likely".

{
  "model": "pocketsflow-penny-1",
  "type": "yes_no",
  "yes": false,
  "confidence": 0.88,
  "probs": [0.12, 0.88],
  "auto": true,
  "usage": { "free_remaining": 957, "credits_remaining": 0 }
}

Confidence and `auto`

confidence is Penny’s calibrated probability that its answer is right: across many answers given at 0.9, about 9 in 10 are correct.

choice and yes_no: the probability of the chosen answer.
score: the probability that the true score is within one point of the rounded score.

auto is true when confidence reaches the threshold for the question type, the point where Penny’s answers were right often enough to act on without a person:

Type	`auto` from
`choice`	0.79
`yes_no`	0.72
`score`	0.8

The pattern: act on auto: true answers, and send the rest to a person with Penny’s answer as a suggestion.

const res = await fetch("https://api.pocketsflow.com/v1/penny/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POCKETSFLOW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    state: payout,
    question: "Should we release this payout now?",
    type: "yes_no",
  }),
});
const decision = await res.json();
if (decision.auto) {
  decision.yes ? await releasePayout(payout) : await holdPayout(payout);
} else {
  await askATeammate(payout, decision);
}

Pricing: free tier, then credits

1,000 free decisions per account every calendar month (UTC). The count resets on the 1st.
After that, each decision uses one prepaid credit: $10 buys 100,000 decisions. The free tier is always used first.
Only answered decisions count. A request that fails validation or that the model could not answer (502) is never counted.

When the month’s free decisions are used and no credits are left, the API answers 402, with a checkout link for more credits in buy_url:

{
  "error": "penny_credits_exhausted",
  "message": "You have used your 1,000 free Penny decisions this month and have no credits left. Buy credits at buy_url to keep going.",
  "buy_url": "https://buy.polar.sh/polar_c_..."
}

Check your usage

curl https://api.pocketsflow.com/v1/penny/usage \
  -H "Authorization: Bearer pk_live_..."

{
  "free_limit": 1000,
  "free_used": 42,
  "free_remaining": 958,
  "credits_remaining": 0,
  "buy_url": "https://buy.polar.sh/polar_c_..."
}

credits_remaining is null when the balance could not be read right now; buy_url is null when credits are not on sale.

Errors

Status	`error`	Meaning
`400`	`invalid_request`	The body failed validation; `message` says which field.
`401`		Missing or invalid API key.
`402`	`penny_credits_exhausted`	Free decisions used and no credits left. Buy more at `buy_url`.
`429`		Rate limited (600 requests per minute per account).
`502`	`penny_inference_failed`	The model did not answer. Nothing was counted; retry.
`503`	`penny_unavailable`	Penny is switched off. Retry later.
`503`	`penny_billing_unavailable`	Free decisions used and your credit balance could not be read. Retry in a moment.

Try it without a key

The Penny playground asks the same model from your browser, no account needed.

Overview

API reference

Node.js SDK

Webhooks

Ask a question

The three question types

Confidence and `auto`

Pricing: free tier, then credits

Check your usage

Errors

Try it without a key

​Ask a question

​The three question types

​Confidence and auto

​Pricing: free tier, then credits

​Check your usage

​Errors

​Try it without a key

Ask a question

The three question types

Confidence and `auto`

Pricing: free tier, then credits

Check your usage

Errors

Try it without a key