AgentCard
Docs Pricing Log in

API Documentation

Everything you need to integrate AgentCard into your AI agent.

Quick Start

Base URL: https://api.agent-card.sh/v1

All requests require a Bearer token in the Authorization header. 

curl https://api.agent-card.sh/v1/cards \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

API keys are created from your dashboard. Each key has scoped permissions:

Scope Description
cards:read List and view cards
cards:write Create cards, change card status
transactions:read List and view transactions

Cards

GET /v1/cards cards:read

List all cards

curl https://api.agent-card.sh/v1/cards \
  -H "Authorization: Bearer ak_..."
POST /v1/cards cards:write

Create a new card

curl -X POST https://api.agent-card.sh/v1/cards \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"card": {"name": "My Agent", "spend_limit_cents": 10000}}'

Parameters

Field Type Required Description
name string Yes Display name for the card
spend_limit_cents integer Yes Maximum spend per transaction in cents
currency string No ISO 4217 code (default: USD)
memo string No Internal note
GET /v1/cards/:id cards:read

Get a specific card

POST /v1/cards/:id/approve cards:write

Approve a pending card

POST /v1/cards/:id/activate cards:write

Activate an approved card

POST /v1/cards/:id/freeze cards:write

Freeze an active card

POST /v1/cards/:id/close cards:write

Permanently close a card

POST /v1/cards/:id/fund cards:write

Fund a card from your default payment method

Parameters

Field Type Required Description
amount_cents integer Yes Amount to fund in cents (a 5.9% + 30¢ fee applies)

Transactions

GET /v1/cards/:card_id/transactions transactions:read

List transactions for a card

GET /v1/transactions/:id transactions:read

Get a specific transaction

Card Status Flow

Cards follow a strict state machine:

  pending_approval
       │
       ▼
    approved ──────────┐
       │               │
       ▼               │
    active ◄──► frozen │
       │         │     │
       ▼         ▼     ▼
            closed

Code Examples

Python

import requests
API_KEY = "ak_..."
BASE = "https://api.agent-card.sh/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}
# Create a card
card = requests.post(f"{BASE}/cards", json={
    "card": {"name": "GPT Agent", "spend_limit_cents": 5000}
}, headers=headers).json()
# List transactions
card_id = card["data"]["id"]
txns = requests.get(
    f"{BASE}/cards/{card_id}/transactions",
    headers=headers
).json()

JavaScript / TypeScript

const API_KEY = "ak_...";
const BASE = "https://api.agent-card.sh/v1";
const headers = { Authorization: `Bearer ${API_KEY}` };
// Create a card
const card = await fetch(`$BASE/cards`,
  method: "POST",
  headers: ...headers, "Content-Type": "application/json",
  body: JSON.stringify({
    card: { name: "GPT Agent", spend_limit_cents: 5000 }
  })
).then(r => r.json());

CLI (agentcard)

pip install git+https://github.com/iurimadeira/agentcard#subdirectory=cli
agentcard configure --key ak_...
agentcard cards create --name "GPT Agent" --limit 5000
agentcard cards list
agentcard cards approve CARD_ID
agentcard cards activate CARD_ID
agentcard transactions list --card CARD_ID

Rate Limits

Authentication Limit Window
Authenticated (API key) 100 requests Per minute
Unauthenticated (IP) 60 requests Per minute

Rate-limited responses return HTTP 429 with a Retry-After header.

Error Responses

All errors return JSON with an errors key: 

{"errors": {"detail": "Not Found"}}
Status Meaning
400 Bad request — missing or invalid parameters
401 Unauthorized — invalid or missing API key
403 Forbidden — API key lacks required scope
404 Not found — resource doesn't exist
422 Validation error — check the errors object
429 Rate limited — slow down