> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Penny decision API

> Ask Pocketsflow Penny 1 one typed question about a situation and get the answer with a calibrated confidence. 1,000 free decisions a month.

**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](https://www.pocketsflow.com/research/penny).

Base URL `https://api.pocketsflow.com`, API key in the `Authorization`
header, like every other endpoint. Available on every plan.

## Ask a question

```bash theme={"system"}
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"]
  }'
```

```json theme={"system"}
{
  "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"`.

```json theme={"system"}
{
  "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.

```js theme={"system"}
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`:

```json theme={"system"}
{
  "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

```bash theme={"system"}
curl https://api.pocketsflow.com/v1/penny/usage \
  -H "Authorization: Bearer pk_live_..."
```

```json theme={"system"}
{
  "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](https://www.pocketsflow.com/research/penny/playground)
asks the same model from your browser, no account needed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.