Reference

API Reference

The Code_ REST API powers both the dashboard and the CLI. All endpoints require authentication via NextAuth session cookies or bearer tokens. Base URL: https://codecard.ai/api

Authentication

The API uses NextAuth.js for authentication. For browser-based access, session cookies are set automatically after login. For programmatic access, authenticate via the credentials endpoint.

POST /api/auth/callback/credentials
Content-Type: application/x-www-form-urlencoded

email=sarah@dev.io&password=password&csrfToken=TOKEN

All subsequent requests must include the session cookie. Unauthenticated requests return 401.

Projects

GET /api/projects

List all projects for the authenticated user.

Response

[
  {
    "id": "proj_001",
    "name": "ai-tutor-app",
    "description": "AI-powered tutoring platform",
    "status": "active",
    "color": "#b8f036",
    "monthlyBudget": 5000,
    "createdAt": "2026-01-10T08:00:00.000Z"
  }
]

POST /api/projects

Create a new project. A virtual Visa card is automatically provisioned.

Field	Type	Required	Description
name	string	Yes	Project name (must be unique per user)
description	string	No	Project description
budget	number	No	Monthly budget in dollars (default: 2000)

Request

POST /api/projects
Content-Type: application/json

{
  "name": "my-new-app",
  "budget": 3000
}

GET /api/projects/:id

Get project details including P&L (spend, revenue, margin) and all transactions.

Response

{
  "project": { "id": "proj_001", "name": "ai-tutor-app", ... },
  "pnl": {
    "spend": 2340,
    "revenue": 8120,
    "net": 5780,
    "margin": 71.2,
    "topProviders": [
      { "name": "OpenAI", "amount": 1200 },
      { "name": "Anthropic", "amount": 680 }
    ]
  },
  "transactions": [ ... ]
}

Virtual Cards

GET /api/cards

List all virtual cards with project info, status, and spend limits.

Response

[
  {
    "id": "card_001",
    "last4": "4096",
    "status": "active",
    "currentMonthSpend": 2340,
    "monthlyLimit": 5000,
    "project": { "name": "ai-tutor-app", "color": "#b8f036" }
  }
]

PATCH /api/cards/:id

Update a card — freeze/unfreeze or change spend limits.

Field	Type	Description
status	string	"active" or "frozen"
dailyLimit	number	Daily spend limit in dollars
monthlyLimit	number	Monthly spend limit in dollars

Freeze a card

PATCH /api/cards/card_001
Content-Type: application/json

{ "status": "frozen" }

Spend

GET /api/spend

Get spend breakdown by category, provider, and project. Optionally filter by project.

Param	Type	Description
projectId	string (query)	Filter transactions to a specific project

Response

{
  "totalSpend": 7920,
  "byCategory": [
    { "category": "ai-apis", "amount": 4680, "percentage": 59.1 }
  ],
  "byProvider": [
    { "provider": "OpenAI", "amount": 3000, "percentage": 37.9 }
  ],
  "byProject": [
    { "projectId": "proj_003", "projectName": "client-dashco", "amount": 4100 }
  ],
  "transactions": [ ... ]
}

Balance

GET /api/balance

Get account balance and credit utilization.

Response

{
  "available": 12400,
  "pending": 340,
  "creditLimit": 25000,
  "creditUsed": 7890
}

Rewards

GET /api/rewards

Get Code Credits balance, reward tiers with per-category breakdowns, and transaction history.

Response

{
  "balance": {
    "totalCredits": 142.30,
    "pendingCredits": 18.50,
    "lifetimeEarned": 342.30,
    "lifetimeRedeemed": 200
  },
  "tiers": [
    { "category": "AI Model APIs", "rate": 5, "earned": 234, "spend": 4680 }
  ],
  "history": [
    { "type": "earned", "amount": 45, "description": "5% on OpenAI" }
  ]
}

Alerts

GET /api/alerts

Get alert rules and triggered alert events.

Response

{
  "rules": [
    { "type": "spend-spike", "threshold": 3, "autoFreeze": false }
  ],
  "events": [
    {
      "severity": "critical",
      "title": "Spend spike detected",
      "message": "OpenAI spend jumped 340%...",
      "acknowledged": false,
      "triggeredAt": "2026-03-27T14:30:00Z"
    }
  ]
}

Error Responses

Status	Meaning
401	Unauthorized — missing or invalid session
400	Bad request — missing required fields
404	Not found — resource doesn't exist or doesn't belong to user
429	Rate limited (waitlist endpoint only)
500	Server error

All errors return JSON: { "error": "message" }

code_

Home Dashboard GitHub