API Overview

Base URL

https://codecosts.com/api

In development: http://localhost:3016/api

Authentication

Most endpoints require authentication. Include one of:

• Clerk session: Automatic via __session cookie (browser requests)
• API key: Authorization: Bearer sk_xxx (CLI / SDK)

The proxy endpoint (/proxy/:slug/v1/messages) uses your Anthropic API key directly — not a Codecosts API key.

Request format

All request bodies use JSON. Set Content-Type: application/json.

Response format

All responses return JSON. Successful responses return the resource directly. Errors return:

{
  "error": "Human-readable error message",
  "details": "Optional validation details"
}

Status codes

Code	Meaning
200	Success
201	Created (POST /api/api-keys)
400	Validation error (check details field)
401	Not authenticated
404	Resource not found
429	Rate limited (check retryAfter field)
500	Server error

Rate limits

Scope	Limit
Global (all endpoints)	600 requests / minute per IP
Proxy /v1/messages	300 requests / minute per proxy endpoint
Proxy /v1/messages/count_tokens	600 requests / minute per proxy endpoint

Endpoints

Proxy

Method	Endpoint	Auth	Description
POST	/proxy/:slug/v1/messages	Anthropic key	Proxy requests to Anthropic API — logs usage, cost, and bodies
POST	/proxy/:slug/v1/messages/count_tokens	Anthropic key	Passthrough to Anthropic token counter (no logging)

Proxy endpoint management

Method	Endpoint	Auth	Description
GET	/api/proxy-endpoints	Yes	List proxy endpoints (paginated)
POST	/api/proxy-endpoints	Yes	Create proxy endpoint
DELETE	/api/proxy-endpoints/:id	Yes	Delete proxy endpoint

Usage tracking

Method	Endpoint	Auth	Description
GET	/api/usage/summary	Yes	Aggregated usage stats (by model, by day)
GET	/api/usage	Yes	Paginated usage logs (filterable by model, date, endpoint)
GET	/api/usage/:id	Yes	Single usage log detail with request/response bodies

API key management

Method	Endpoint	Auth	Description
GET	/api/api-keys	Yes	List API keys (paginated)
POST	/api/api-keys	Yes	Create API key (full key returned once)
DELETE	/api/api-keys/:id	Yes	Delete API key

User profile

Method	Endpoint	Auth	Description
GET	/api/profile	Yes	Get current user profile
PUT	/api/profile	Yes	Update display name

Audit and system

Method	Endpoint	Auth	Description
GET	/api/audit-logs	Yes	Paginated action trail
GET	/api/health	No	Health check with DB latency