PINTI Docs

Quickstart

Go from zero to your first spend evaluation in 5 minutes.

1

Create your workspace

Sign up at pinti.ai and create your workspace. A default payment handle is created automatically.

2

Get your API key

Go to Dashboard → API Keys and click Generate Key. Copy the key — you won't see it again.

Set your environment variable
export PINTI_API_KEY="pinti_xxxxxxxx_..."
3

Create a policy

Go to Dashboard → Policies and create your first policy. For example:

  • Max single amount: $100
  • Daily limit: $500
  • Require approval over: $50

Or create it via the API:

Create policy via API
curl -X POST https://pinti.ai/api/v1/policies \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PINTI_API_KEY" \
  -d '{
    "name": "Default Policy",
    "maxSingleAmount": 10000,
    "dailyLimit": 50000,
    "requireApprovalOver": 5000,
    "unit": "USD"
  }'
4

Evaluate a spend intent (curl)

POST /api/v1/spend/evaluate
curl -X POST https://pinti.ai/api/v1/spend/evaluate \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PINTI_API_KEY" \
  -d '{
    "agentId": "my-agent",
    "amountMinor": 3000,
    "unit": "USD",
    "merchant": "openai.com",
    "category": "api",
    "reason": "Monthly API credits"
  }'

Response:

{
  "decision": "ALLOW",
  "decisionReason": "OK",
  "spendRequestId": "cm..."
}
5

Evaluate using the SDK

Install
npm install @pinti/guard
evaluate.ts
import { PintiGuard } from "@pinti/guard";

const pinti = new PintiGuard({ apiKey: process.env.PINTI_API_KEY! });

const auth = await pinti.authorize({
  agentId: "my-agent",
  amountMinor: 3000,   // $30.00 in cents
  currency: "usd",
  merchant: "openai.com",
  category: "api",
  reason: "Monthly API credits",
});

console.log(auth.decision);
// "ALLOW" — auth.sat contains the authorization token

console.log(result.decisionReason);
// "OK" | "EXCEEDS_SINGLE_LIMIT" | etc.

console.log(result.spendRequestId);
// "cm..."  — use for approval polling

Understanding Decisions

DecisionSDK StatusWhat to Do
ALLOWallowedProceed with the payment
DENYdeniedStop. Explain to the user why it was denied.
REQUIRE_APPROVALneeds_approvalWait for human approval. Use callbackUrl for instant notification, or poll with getSpendRequestStatus(). See Approvals & Callbacks.

Common Gotchas

Warning

  • Base URL — The API base is https://pinti.ai, not https://pinti.ai/api. The SDK appends /api/v1/spend/evaluate automatically.
  • Headers — Use x-api-key (lowercase), not Authorization.
  • Environment variables — SDK reads PINTI_API_KEY and PINTI_URL from env automatically.
  • Unit matching — The intent's unit must match the policy unit. Use uppercase: USD, not usd.