CostVaneDocs

API documentation

Control AI cost in three requests.

Use CostVane beside your existing model-provider integration. Estimate a request, evaluate budgets, then record actual usage—without sending prompts, outputs, or provider credentials.

Base URLhttps://api.costvane.com

Quickstart

Send token counts and the provider/model identifier to receive a detailed estimate.

cURL
curl https://api.costvane.com/v1/estimate \
  -X POST \
  -H "X-API-Key: $COSTVANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-5.4-mini",
    "inputTokens": 1000,
    "cachedInputTokens": 500,
    "outputTokens": 200
  }'
Response
{
  "provider": "openai",
  "model": "gpt-5.4-mini",
  "totalCost": 0.00069,
  "inputCost": 0.000375,
  "cachedInputCost": 0.000019,
  "outputCost": 0.0003,
  "currency": "USD",
  "pricingSource": {
    "type": "official",
    "url": "https://developers.openai.com/api/docs/pricing"
  }
}

Authentication

All /v1 endpoints require an API key in the X-API-Key request header. Keep keys server-side and never expose them in browser code or public repositories.

Design-partner access

Production keys are currently issued during onboarding. Email support@costvane.com to request access.

POST/v1/estimate

Estimate a request

Returns input, cached-input, output, and total cost using the versioned provider catalog. Use it for price previews and routing decisions.

FieldTypeDescription
providerstringopenai, anthropic, google, or openrouter
modelstringCatalog model identifier
inputTokensintegerNon-cached input tokens
cachedInputTokensintegerOptional cached input tokens
outputTokensintegerGenerated output tokens
POST/v1/preflight

Evaluate budgets before execution

Combines a cost estimate with every matching active budget and returns allow, warn, or block.

Request
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "inputTokens": 4200,
  "outputTokens": 900,
  "customerId": "cust_123",
  "feature": "research-agent"
}
POST/v1/usage

Record actual usage

Send the provider-reported actual cost when available. Add an Idempotency-Key header so network retries do not double-count the event.

Request
{
  "provider": "openai",
  "model": "gpt-5.4-mini",
  "inputTokens": 1000,
  "outputTokens": 200,
  "actualCost": 0.00072,
  "customerId": "cust_123",
  "feature": "copilot",
  "environment": "production",
  "tags": { "plan": "pro" }
}
GET/v1/usage/summary

Summarize and attribute spend

Query by period=day|week|month and optionally group by customer, feature, workflow, team, project, or environment.

GET /v1/usage/summary?period=month&groupBy=customer

Budgets

Create dollar or token limits with POST /v1/budgets. Budgets can apply globally or to a customer, feature, workflow, team, project, or environment. Enforcement can warn or block.

Webhooks

Register an HTTPS endpoint with POST /v1/webhooks. CostVane encrypts the signing secret at rest and signs events using HMAC-SHA256. Private-network destinations are rejected.

Errors and request IDs

Error responses use a stable code and a safe human-readable message. Every response includes an X-Request-Id header for support and log correlation.

StatusMeaningAction
400Invalid requestCheck the payload and model identifier
401UnauthorizedSupply a valid X-API-Key
429Rate or quota limitRetry later or upgrade the plan