Back to Home
Lumos Docs

Quick Start & API Reference

Integrate SDKs, export usage data, use model routing, and enable cache proxy endpoints.

SDK Setup

Python

pip install costpilot

import costpilot
costpilot.init(api_key="cp_xxx")

Node.js

npm install costpilot

import { init } from 'costpilot';
init({ apiKey: 'cp_xxx' });
API Endpoints
POST
/api/v1/events

Track Events

curl -X POST "$BASE/api/v1/events" \
  -H "Authorization: Bearer cp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o","prompt_tokens":1200,"completion_tokens":400}'
GET
/api/v1/export?format=csv&from=2026-03-01T00:00:00Z

Export Logs (CSV)

curl -H "Authorization: Bearer cp_xxx" \
  "$BASE/api/v1/export?format=csv&include_content=true" -o events.csv
POST
/api/v1/route-model

Route Model

curl -X POST "$BASE/api/v1/route-model" \
  -H "Authorization: Bearer cp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"objective":"balanced","estimatedPromptTokens":1200,"estimatedCompletionTokens":400}'
POST
/api/v1/proxy

Proxy (Cache + Routing)

curl -X POST "$BASE/api/v1/proxy" \
  -H "Authorization: Bearer cp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o","prompt":"Summarize this...","objective":"cost"}'
GET
/api/v1/cache?provider=openai&model=gpt-4o&prompt=Hello

Cache Lookup

curl -H "Authorization: Bearer cp_xxx" \
  "$BASE/api/v1/cache?provider=openai&model=gpt-4o&prompt=Hello"
POST
/api/v1/cache

Cache Store

curl -X POST "$BASE/api/v1/cache" \
  -H "Authorization: Bearer cp_xxx" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o","prompt":"Hello","response":"Hi there!","ttl_seconds":3600}'
GET
/api/v1/forecast?lookback_days=30&horizon_days=7

Forecast

curl -H "Authorization: Bearer cp_xxx" \
  "$BASE/api/v1/forecast?lookback_days=30&horizon_days=7"
Prompt Versioning & Team

Open /dashboard/prompts to manage prompt versions, or /dashboard/team to manage team members.

Use prompt versions to roll back templates safely without editing live content directly.

Team members can view dashboards immediately after being added to a project.