API Reference¶

Cost Guard backend API for programmatic access.

Base URL¶

https://api.costcut.dev/v1/

Authentication¶

Two auth methods:

Type	Use	Header
JWT	User endpoints (auth, keys, billing)	`Authorization: Bearer <access_token>`
API Key	CLI ingest (sessions, usage)	`Authorization: Bearer cg_live_<key>`

Auth Endpoints¶

POST /auth/signup¶

Create new account.

Request:

{
  "email": "[email protected]",
  "password": "secure_password"
}

Response (201):

{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

POST /auth/login¶

Authenticate user.

Request:

{
  "email": "[email protected]",
  "password": "secure_password"
}

Response (200):

{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

GET /auth/me¶

Get current user info (requires JWT).

Response (200):

{
  "id": "user_123",
  "email": "[email protected]",
  "plan": "Pro"
}

Keys Endpoints¶

POST /keys¶

Create new API key (requires JWT).

Request:

{
  "name": "my-cli-key"
}

Response (201):

{
  "id": "key_123",
  "key": "cg_live_abc123...",
  "prefix": "cg_live",
  "name": "my-cli-key"
}

GET /keys¶

List API keys (requires JWT).

Response (200):

[
  {
    "id": "key_123",
    "prefix": "cg_live",
    "name": "my-cli-key",
    "last_used_at": "2026-05-23T10:00:00Z",
    "created_at": "2026-05-20T14:30:00Z"
  }
]

Sessions Endpoints¶

POST /sessions¶

Upload session data (requires API Key or JWT).

Request:

{
  "project_id": "cost-guard",
  "model": "claude-3-5-sonnet",
  "input_tokens": 2500,
  "output_tokens": 1200,
  "cache_hits": 50,
  "cost_usd": 0.01,
  "date": "2026-05-23"
}

Response (201):

{
  "id": "session_456",
  "project_id": "cost-guard",
  "model": "claude-3-5-sonnet",
  "cost_usd": 0.01,
  "created_at": "2026-05-23T10:00:00Z"
}

GET /sessions¶

List user's sessions (requires JWT).

Query params:

Param	Type	Default	Description
`project_id`	string	—	Filter by project
`model`	string	—	Filter by model
`since`	ISO 8601	—	Sessions after this date
`limit`	int	50	Max results

Response (200):

[
  {
    "id": "session_456",
    "project_id": "cost-guard",
    "model": "claude-3-5-sonnet",
    "input_tokens": 2500,
    "output_tokens": 1200,
    "cost_usd": 0.01,
    "date": "2026-05-23"
  }
]

Billing Endpoints¶

POST /billing/checkout¶

Create Stripe checkout session (requires JWT).

Request:

{
  "plan": "Pro"
}

Response (200):

{
  "checkout_url": "https://checkout.stripe.com/pay/cs_..."
}

POST /billing/webhook¶

Stripe webhook (public endpoint, no auth).

Called by Stripe on payment events (payment_intent.succeeded, customer.subscription.updated).

Error Responses¶

Code	Meaning
400	Bad Request — invalid params
401	Unauthorized — missing/invalid auth
409	Conflict — email already registered
500	Server Error — try again later

Example error:

{
  "detail": "Email already registered"
}