# Create and run an AI agent over HTTP with Pizza Ex Machina's API

Pizza Ex Machina turns plain-text instructions into a standing agent behind an HTTP endpoint, which you run with fresh input whenever you need it. Creating an agent is free, and each run draws $0.01 per run plus the oven's per-token rates from prepaid credit. Buy at least $0.50 of credit on the storefront, redeem a `pxm_live_` key, then send create and run calls to `https://api.pizzaexmachina.com` with that key.

## At a glance

- **Buy credit:** `POST https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/plans/{planId}/purchase` with a bearer credential and `amountUsd`. The minimum is $0.50, or $0.50 by card. The Credits plan's id is in [the catalog](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/manifest.json).
- **Payment:** the purchase returns one 402 price quote. Pay it over x402, MPP or card, then retry. API calls carry no payment.
- **Key:** `POST https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/keys/redeem` returns a `pxm_live_` key, shown once.
- **Create (free):** `POST https://api.pizzaexmachina.com/v1/agents` with `instructions`, `model` and `name`.
- **Run:** `POST https://api.pizzaexmachina.com/v1/agents/{agentId}/runs` with `input`. Each run is billed $0.01 per run plus token rates.
- **Response:** `output`, `model`, a `billed` breakdown and `remainingCreditUsd`.
- **Limits:** 4,000 characters of instructions, 4,000 characters of input, and 1,200 output tokens per run.
- **Full purchase flow:** [the buyer skill](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/SKILL.md)

## Two hosts, two credentials

| Host | Credential | Used for |
| --- | --- | --- |
| `https://agents.pizzaexmachina.com/zcj/risxiu4egwcw` | Bearer access token, exchanged from the agent identity the storefront issues | Buying credit, redeeming keys, topping up, recovery |
| `https://api.pizzaexmachina.com` | `pxm_live_` key | Creating, listing and running agents, and reading the balance |

## Buy credit, create an agent and run it

1. Exchange your stored agent credential for an access token. A bearer credential is the agent identity the storefront issues. If you don't have one, follow the registration steps in [Identity](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/auth.md).

   ```bash
   curl -s https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/oauth2/token \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
     --data-urlencode "assertion=$ASSERTION"
   ```

   The response carries `access_token`. It lasts minutes, so exchange again when it expires. An anonymous credential that no human has claimed lapses within days, taking any account bought with it. Have your human claim it to a verified email.

2. Check for an existing account before you buy.

   ```bash
   curl -s https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/purchases/receipt -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   The `purchases` array lists each account with its `accessId`, `provisioningState`, `redeemUrl` and `topUpUrl`. If a Credits account is already there, skip to step 4.

3. Buy the Credits plan. Set `amountUsd` to a whole-cent decimal string at or above the minimum.

   ```bash
   curl -s -X POST "https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/plans/{planId}/purchase" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"amountUsd": "<amount>"}'
   ```

   The storefront first answers with a 402. This is the price quote: pay it and retry the identical request. An x402 or MPP client does this for you. To pay by card, add `"checkout": true` to get a hosted checkout page.

   A successful purchase returns `purchased: true` and an `access` block with `accessId` (`zacc_...`), `provisioningState` and `redeemUrl`. Your money is captured only after Pizza Ex Machina confirms the account exists. If provisioning fails, the payment is released.

4. Redeem the key. Add `"accessId"` to the body only if you hold more than one account.

   ```bash
   curl -s -X POST https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/keys/redeem \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H 'Content-Type: application/json' -d '{}'
   ```

   A `503` with `"error": "provisioning"` means the account is still being set up. Wait `retryAfterSeconds` and retry the redeem, never the purchase. A successful redeem returns `accessId`, `apiKey`, `maxKeys` and `keyExpiresAt`. Store `apiKey` immediately, because it is shown once.

5. Create the agent, and always set `model`. A body without `model` gets `forno-1`.

   ```bash
   curl -s -X POST https://api.pizzaexmachina.com/v1/agents \
     -H "Authorization: Bearer $PXM_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"name": "Headline Writer", "model": "forno-1", "instructions": "Write one headline of under 70 characters for the text you are given. Return only the headline, with no quotation marks."}'
   ```

   The response returns `agent` with `id`, `name`, `instructions`, `model` set to `forno-1`, an empty `tools` list and `createdAt`. It also returns `runUrl`, the address for runs. This example took 0.3 seconds.

6. Run the agent with fresh input.

   ```bash
   curl -s -X POST https://api.pizzaexmachina.com/v1/agents/{agentId}/runs \
     -H "Authorization: Bearer $PXM_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"input": "The city library will open on Sundays from November, with longer evening hours on weekdays and a new self-checkout desk by the entrance."}'
   ```

   The response has this shape, with the amounts omitted here:

   ```json
   {"agent": {"id": "chef_ORtLxyjmDf3F", "name": "Headline Writer"},
    "output": "Library Extends Hours, Adds Sunday Service",
    "model": "forno-1",
    "billed": {"runUsd": "…", "inputTokens": 120, "inputTokensUsd": "…", "outputTokens": 12, "outputTokensUsd": "…", "totalUsd": "…"},
    "remainingCreditUsd": "…"}
   ```

   This example run drew $0.010189 from credit and took 1.8 seconds. In the response, `billed.totalUsd` is the run fee plus the input and output token costs, and `remainingCreditUsd` is the balance after the run. `GET https://api.pizzaexmachina.com/v1/account` with the key also returns the balance.

## Choose the oven

The oven is the model an agent runs on, fixed when you create it: `fornetto-1`, `forno-1` or `inferno-1`. On `forno-1`, input costs $1.05 per million tokens and output $5.25 per million tokens.

## Top up when credit runs out

The API starts a run only while the balance can pay the run fee. The full cost is debited after the model responds, so the last run can leave the balance slightly negative. After that, runs answer `402 insufficient_credit`. Add credit to the same account:

```bash
curl -s -X POST https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/extend \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"amountUsd": "<amount>", "accessId": "zacc_..."}'
```

The top-up uses the same 402 payment as the purchase. A successful top-up returns `extended: true`, with the new balance in `access.remainingCreditUsd`. The key and the agents are unchanged.

## Boundaries

- An agent's instructions and oven are fixed when you create it. To use a different oven, create a new agent.
- Each run takes one `input` string and returns one `output`.
- Creating and listing agents is free. Only runs draw credit, and a `502 run_failed` is not billed.
- Nothing is charged until you pay the purchase or top-up 402.

## Errors

| Status and code | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | A purchase was sent without the bearer | Register at [Identity](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/auth.md) and retry |
| `400 amount_below_minimum` | `amountUsd` is under the plan minimum | Send at least $0.50 |
| `401 unauthorized` / `401 invalid_api_key` | No key was sent, or the key is wrong or revoked | Send the `pxm_live_` key, not the bearer |
| `402 insufficient_credit` | The balance can't cover the run fee | Top up with `POST https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/extend` |
| `502 run_failed` | The inference backend was unavailable | Retry later. The failed run was not billed |

## Frequently asked questions

### What if the pxm_live_ key is lost?

Redeem again from the same account at `https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/keys/redeem`. When `maxKeys` is 1, the new key replaces the old one. If the purchase carried a verified email, your human can also sign in at [pizzaexmachina.com/account](https://pizzaexmachina.com/account) and generate a new key, which revokes the previous one. You never need to buy again to recover a key.

### Can an agent's instructions or oven be changed after creation?

No. Both are fixed when the agent is created. To change them, create a new agent with the new instructions or `model`. Creating it is free.

### Is there a free trial?

Yes. The Free trial gives free starting credit, one per human. You claim it with the same purchase call and an empty body, using a credential your human has claimed with a verified email. Until that claim exists, the purchase answers `403 verified_email_required`.

### Does each run need its own payment?

No. Each run is billed against prepaid credit on your account, and the API calls carry only the key. The only payment is the 402 when you buy or top up credit on the storefront.

### Does the storefront bearer work on api.pizzaexmachina.com?

No. The bearer buys, redeems and recovers on the storefront. The `pxm_live_` key is the only credential the API accepts.

## Keep reading

- [Buyer skill](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/SKILL.md): the full purchase and recovery flow
- [Standing accounts](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/accounts.md): provisioning, key redemption and top-ups
- [Identity](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/auth.md): registering and claiming an agent credential
- [How to pay](https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/payment.md): the 402 and each payment rail
- [Pizza Ex Machina API reference](https://pizzaexmachina.com/docs)

---

Updated 2026-10-12. All Pizza Ex Machina guides: https://agents.pizzaexmachina.com/guides.md. Storefront: https://agents.pizzaexmachina.com/zcj/risxiu4egwcw/llms.txt.