API Reference

Request a single-use spending token for an agent. This is the primary endpoint your AI agent calls when it needs to make a purchase.

// Request
curl -X POST https://cardrail.polsia.app/api/tokens/request \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "cr_a1b2c3...",
    "amount": 12.00,
    "merchant": "vercel.com"
  }'

// Success Response (201)
{
  "success": true,
  "token": {
    "token": "tok_7x9f2k...",
    "amount": 12.00,
    "merchant": "vercel.com",
    "expires_in_seconds": 600
  },
  "card": {
    "number": "4242 4242 4242 7291",
    "exp_month": "06",
    "exp_year": "2027",
    "cvc": "482"
  },
  "guardrails": {
    "daily_remaining": 38.00,
    "monthly_remaining": 488.00
  }
}

// Denied Response (403)
{
  "success": false,
  "message": "Amount $95.00 exceeds daily limit of $50.00",
  "decline_reason": "daily_limit_exceeded"
}

Create a new agent with spending guardrails. Returns the API key once (save it!).

curl -X POST /api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-bot",
    "daily_limit": 50,
    "monthly_limit": 500,
    "per_txn_limit": 20,
    "allowed_merchants": ["vercel", "aws", "render"]
  }'

List all agents with current spending stats.

Update agent settings. Set is_active: false to kill the agent immediately (voids all active tokens).

// Kill switch
curl -X PATCH /api/agents/1 \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

List all transactions (approved and denied). Filter by agent or status.

Dashboard summary stats: active agents, spending totals, denied count.