The AgentRefills REST API

Four rules that hold for every call

Learn these once and the whole API is predictable. They are enforced on the server, so an agent can lean on them instead of guessing.

• Bearer auth, per agent. Send Authorization: Bearer <API_KEY> on every request. Each key is scoped to one agent with its own daily and monthly caps and brand allowlist.
• Money is integer minor units. amount_minor: 2500 means $25.00. There are no floats anywhere in the API.
• Idempotency via client_ref. Supply a client_ref on a purchase. Re-using it returns the existing task and never charges twice.
• Purchases are async. POST /v1/purchases returns a task_id right away. Poll GET /v1/purchases/{task_id} or subscribe to the purchase.completed webhook, then release the code.

Six operations, one per tool

Every REST endpoint maps 1:1 to an MCP tool. Branch on the response, act on the hint.

# 1. Start the purchase. Returns a task_id right away
$ curl -sS https://agentrefills.com/v1/purchases \
    -H "Authorization: Bearer $AGENTREFILLS_KEY" \
    -H "Content-Type: application/json" \
    -d '{"brand_id":"amazon_com-usa","amount_minor":2500,"currency":"USD","client_ref":"reward-9f3a"}'

{ "task_id": "3f1c...", "status": "accepted", "state": "paid", "estimated_seconds": 8 }

# 2. Release the code exactly once (single-read; never logged)
$ curl -sS -X POST https://agentrefills.com/v1/purchases/3f1c.../code \
    -H "Authorization: Bearer $AGENTREFILLS_KEY"

{ "code": "GIFT-XXXX-9F2A", "face_minor": 2500, "remaining_minor": 2500 }

A closed set of twelve error codes

Agents branch on code and act on hint. Every error carries an agent-actionable hint, and RETRYABLE always includes retry_after in seconds.