{"openapi":"3.1.0","info":{"title":"CrbonFree API","version":"1.0.0","description":"Track AI workload carbon emissions: ingest provider telemetry, calculate per-tier CO₂ with versioned factors, generate signed retirement receipts.","contact":{"name":"CrbonFree","url":"https://crbonfree.com"}},"servers":[{"url":"https://api.crbonfree.com","description":"Production"}],"tags":[{"name":"Projects","description":"Workspace organization for telemetry"},{"name":"Usage","description":"Token/cost/carbon aggregates + water-footprint estimate (AIW-290)"},{"name":"Telemetry","description":"Event-level telemetry + emissions detail"},{"name":"Factors","description":"Versioned emissions factor sets behind every calculation (read-only, AIW-9)"},{"name":"Billing","description":"Receipts, audit packs, overage, periods, plan tier"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk-issued session JWT, sent as `Authorization: Bearer <token>`. Obtain it via `clerk.session.getToken()` in the browser SDK."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Long-lived API key issued via POST /api/v1/api-keys. Format: ck_live_<32 chars base64url>. Sent in the X-API-Key header (NOT in Authorization — that header is reserved for the Clerk JWT path)."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string","example":"INSUFFICIENT_PERMISSIONS"},"message":{"type":"string","example":"Insufficient permissions for this organization"},"upgradeUrl":{"type":"string","example":"/billing"},"details":{"type":"object","additionalProperties":{}}},"required":["success","error","message"]},"ProjectPublic":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Default"},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","isDefault","createdAt","updatedAt"]},"ProjectWithUsage":{"allOf":[{"$ref":"#/components/schemas/ProjectPublic"},{"type":"object","properties":{"connectionCount":{"type":"integer","minimum":0},"last30dCo2Kg":{"type":"number","minimum":0}},"required":["connectionCount","last30dCo2Kg"]}]},"UsageSummary":{"type":"object","properties":{"range":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"totals":{"type":"object","properties":{"totalTokens":{"type":"number"},"promptTokens":{"type":"number"},"completionTokens":{"type":"number"},"totalCostUsd":{"type":"number"},"requestCount":{"type":"number"},"carbonKg":{"type":"number"},"electricityKwh":{"type":"number"},"waterLiters":{"type":"number","description":"Estimated water footprint in liters (on-site cooling + off-site generation). ESTIMATE ONLY — never part of the signed Footprint Statement, receipts, or audit packs."},"waterLowerBoundL":{"type":"number","description":"Lower uncertainty bound of the water estimate (liters, ~±50% band)."},"waterUpperBoundL":{"type":"number","description":"Upper uncertainty bound of the water estimate (liters, ~±50% band)."},"offsetCostUsd":{"type":["number","null"],"description":"Deprecated. Returns null after the AIW-13 pricing cutover.","deprecated":true}},"required":["totalTokens","promptTokens","completionTokens","totalCostUsd","requestCount","carbonKg","electricityKwh","waterLiters","waterLowerBoundL","waterUpperBoundL","offsetCostUsd"]},"chart":{"type":"object","properties":{"labels":{"type":"array","items":{"type":"string"}},"datasets":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"data":{"type":"array","items":{"type":"number"}}},"required":["label","data"]}}},"required":["labels","datasets"]}},"required":["range","totals","chart"]},"UsageBreakdownItem":{"type":"object","properties":{"model":{"type":"string"},"promptTokens":{"type":"number"},"completionTokens":{"type":"number"},"totalTokens":{"type":"number"},"requestCount":{"type":"number"},"costUsd":{"type":"number"},"percentage":{"type":"number"},"carbonKg":{"type":"number"},"offsetCostUsd":{"type":["number","null"],"description":"Deprecated. Returns null after the AIW-13 pricing cutover.","deprecated":true},"electricityKwh":{"type":"number"}},"required":["model","promptTokens","completionTokens","totalTokens","requestCount","costUsd","percentage","carbonKg","offsetCostUsd","electricityKwh"]},"DailyUsageRow":{"type":"object","properties":{"date":{"type":"string"},"projectName":{"type":"string"},"promptTokens":{"type":"number"},"completionTokens":{"type":"number"},"totalTokens":{"type":"number"},"requestCount":{"type":"number"},"costUsd":{"type":"number"},"carbonKg":{"type":"number"},"energyKwh":{"type":"number"}},"required":["date","promptTokens","completionTokens","totalTokens","requestCount","costUsd","carbonKg","energyKwh"]},"DailyUsageExportRow":{"type":"object","properties":{"date":{"type":"string"},"project_name":{"type":"string"},"prompt_tokens":{"type":"number"},"completion_tokens":{"type":"number"},"total_tokens":{"type":"number"},"request_count":{"type":"number"},"cost_usd":{"type":"number"},"carbon_kg":{"type":"number"},"energy_kwh":{"type":"number"}},"required":["date","project_name","prompt_tokens","completion_tokens","total_tokens","request_count","cost_usd","carbon_kg","energy_kwh"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}},"required":["page","limit","total","totalPages"]},"TelemetrySummary":{"type":"object","properties":{"total_co2_kg":{"type":"number"},"total_co2_lower_bound_kg":{"type":"number"},"total_co2_upper_bound_kg":{"type":"number"},"total_tokens":{"type":"number"},"cached_vs_uncached":{"type":"object","properties":{"uncached_tokens":{"type":"number"},"cached_tokens":{"type":"number"},"cache_creation_tokens":{"type":"number"},"cached_co2_savings_kg":{"type":"number"}},"required":["uncached_tokens","cached_tokens","cache_creation_tokens","cached_co2_savings_kg"]},"per_model":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string"},"total_tokens":{"type":"number"},"co2_kg":{"type":"number"},"percentage":{"type":"number"}},"required":["model","total_tokens","co2_kg","percentage"]}},"daily_chart":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"co2_kg":{"type":"number"},"tokens":{"type":"number"}},"required":["date","co2_kg","tokens"]}},"factors_version":{"type":"string"},"period":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]}},"required":["total_co2_kg","total_co2_lower_bound_kg","total_co2_upper_bound_kg","total_tokens","cached_vs_uncached","per_model","daily_chart","factors_version","period"]},"TelemetryModel":{"type":"object","properties":{"provider":{"type":"string"},"model":{"type":"string"},"total_tokens":{"type":"number"},"total_co2_kg":{"type":"number"},"event_count":{"type":"integer"},"first_seen":{"type":"string"},"last_seen":{"type":"string"}},"required":["provider","model","total_tokens","total_co2_kg","event_count","first_seen","last_seen"]},"BillingPeriod":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["open","reconciling","ready","closing","closed","failed"]},"totals":{"type":"object","properties":{"inputTokensUncached":{"type":"string"},"inputTokensCached":{"type":"string"},"inputTokensCacheCreation":{"type":"string"},"outputTokens":{"type":"string"},"requestCount":{"type":"string"},"providerCostUsd":{"type":"number"},"carbonKg":{"type":"number"},"electricityKwh":{"type":"number"}},"required":["inputTokensUncached","inputTokensCached","inputTokensCacheCreation","outputTokens","requestCount","providerCostUsd","carbonKg","electricityKwh"]},"factorsVersions":{"type":"array","items":{"type":"string"}},"planTierAtClose":{"type":["string","null"],"enum":["free","starter","growth","scale","enterprise"]},"closedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"stripeInvoiceId":{"type":["string","null"]},"amountChargedCents":{"type":["integer","null"]},"failureReason":{"type":["string","null"],"enum":["payment_failed","aggregation_failed","signing_failed"]},"paidAt":{"type":["string","null"],"format":"date-time"},"readyAt":{"type":["string","null"],"format":"date-time"},"closingAt":{"type":["string","null"],"format":"date-time"},"carbonReceiptId":{"type":["string","null"],"format":"uuid"},"statementId":{"type":["string","null"],"format":"uuid"}},"required":["id","periodStart","periodEnd","status","totals","factorsVersions","planTierAtClose","closedAt","createdAt","stripeInvoiceId","amountChargedCents","failureReason","paidAt","readyAt","closingAt","carbonReceiptId","statementId"]},"RetirementStatus":{"type":"object","properties":{"periodId":{"type":"string","format":"uuid"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["collecting","calculating","awaiting_payment","retiring","retired","pending_signature","action_required"]},"carbonKg":{"type":"number"},"electricityKwh":{"type":"number"},"amountChargedCents":{"type":["integer","null"]},"paidAt":{"type":["string","null"],"format":"date-time"},"closedAt":{"type":["string","null"],"format":"date-time"},"receipt":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"co2Kg":{"type":"number"},"isSigned":{"type":"boolean"},"verificationUrl":{"type":"string"},"pdfUrl":{"type":["string","null"]},"signedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","co2Kg","isSigned","verificationUrl","pdfUrl","signedAt"]}},"required":["periodId","periodStart","periodEnd","status","carbonKg","electricityKwh","amountChargedCents","paidAt","closedAt","receipt"]},"ReceiptListEntry":{"allOf":[{"$ref":"#/components/schemas/BillingPeriod"},{"type":"object","properties":{"receipt":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"co2Kg":{"type":"number"},"serialAllocations":{"type":"array","items":{"type":"object","properties":{"serialNumber":{"type":"string"},"totalKgCo2e":{"type":"number"}},"required":["serialNumber","totalKgCo2e"]}},"verificationUrl":{"type":"string"},"previewUrl":{"type":["string","null"]},"pdfUrl":{"type":["string","null"]},"isSigned":{"type":"boolean"},"signedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","co2Kg","serialAllocations","verificationUrl","previewUrl","pdfUrl","isSigned","signedAt","createdAt"]}},"required":["receipt"]}]},"CarbonReceipt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"billingPeriodId":{"type":"string","format":"uuid"},"co2Kg":{"type":"number"},"serialAllocations":{"type":"array","items":{"type":"object","properties":{"serialNumber":{"type":"string"},"totalKgCo2e":{"type":"number"}},"required":["serialNumber","totalKgCo2e"]}},"verificationUrl":{"type":"string"},"previewUrl":{"type":["string","null"]},"pdfUrl":{"type":["string","null"]},"isSigned":{"type":"boolean"},"statementId":{"type":["string","null"],"format":"uuid"},"signedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","billingPeriodId","co2Kg","serialAllocations","verificationUrl","previewUrl","pdfUrl","isSigned","statementId","signedAt","createdAt"]},"TrustSignedStatement":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"billingPeriodId":{"type":"string","format":"uuid"},"artifactType":{"type":"string","enum":["footprint_statement"]},"statementVersion":{"type":"integer","exclusiveMinimum":0},"status":{"type":"string","enum":["prepared","signed"]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]},"usage":{"type":"object","additionalProperties":{"type":"string"}},"footprint":{"type":"object","additionalProperties":{"type":"string"}},"methodology":{"type":"object","properties":{"factorVersions":{"type":"array","items":{"type":"string"}},"waterFactorVersions":{"type":"array","items":{"type":"string"}},"layers":{"type":["object","null"],"additionalProperties":{}}},"required":["factorVersions","waterFactorVersions","layers"]},"statementUrl":{"type":["string","null"],"format":"uri"},"verificationUrl":{"type":["string","null"],"format":"uri"},"signedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","billingPeriodId","artifactType","statementVersion","status","period","usage","footprint","methodology","statementUrl","verificationUrl","signedAt","createdAt"]},"AuditPack":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"packYear":{"type":"integer"},"packMonth":{"type":"integer","minimum":1,"maximum":12},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"blobUrl":{"type":"string"},"manifestHash":{"type":"string"},"receiptCount":{"type":"integer","minimum":0},"fileCount":{"type":"integer","minimum":0},"totalBytes":{"type":"integer","minimum":0},"generatedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","packYear","packMonth","periodStart","periodEnd","blobUrl","manifestHash","receiptCount","fileCount","totalBytes","generatedAt","createdAt"]},"CarbonFactorVersionSummary":{"type":"object","properties":{"version":{"type":"string","example":"v1.2"},"active":{"type":"boolean"},"layered":{"type":"boolean"},"tierCount":{"type":"integer"},"createdAt":{"type":"string"}},"required":["version","active","layered","tierCount","createdAt"]},"CarbonFactorVersionList":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/CarbonFactorVersionSummary"}}},"required":["versions"]},"CarbonFactor":{"type":"object","properties":{"version":{"type":"string","example":"v1.2"},"modelTier":{"type":"string","example":"medium"},"modelPatterns":{"type":"array","items":{"type":"string"},"description":"Case-insensitive glob patterns; first match wins, most specific tier first."},"energyPerTokenPrefillJ":{"type":"number"},"energyPerTokenDecodeJ":{"type":"number"},"energyPerTokenCachedJ":{"type":"number"},"pue":{"type":"number"},"gridIntensityKgPerKwh":{"type":"number"},"uncertaintyPct":{"type":"number"},"wueLPerKwh":{"type":"number","description":"Water-use effectiveness; 0 on carbon-only v1.0 rows."},"gridWaterLPerKwh":{"type":"number"},"waterUncertaintyPct":{"type":"number"},"hostPowerFactor":{"type":["number","null"],"description":"v1.2 layered-emissions factor; null on legacy v1.0/v1.1 rows."},"clusterUtilization":{"type":["number","null"],"description":"v1.2 layered-emissions factor; null on legacy v1.0/v1.1 rows."},"embodiedKgPerMtok":{"type":["number","null"],"description":"v1.2 layered-emissions factor; null on legacy v1.0/v1.1 rows."},"trainingKgPerMtok":{"type":["number","null"],"description":"v1.2 layered-emissions factor; null on legacy v1.0/v1.1 rows."},"activityUncertaintyPct":{"type":["number","null"],"description":"v1.2 layered-emissions factor; null on legacy v1.0/v1.1 rows."},"emissionFactorUncertaintyPct":{"type":["number","null"],"description":"v1.2 layered-emissions factor; null on legacy v1.0/v1.1 rows."},"createdAt":{"type":"string","description":"ISO-8601; when the version was seeded."}},"required":["version","modelTier","modelPatterns","energyPerTokenPrefillJ","energyPerTokenDecodeJ","energyPerTokenCachedJ","pue","gridIntensityKgPerKwh","uncertaintyPct","wueLPerKwh","gridWaterLPerKwh","waterUncertaintyPct","hostPowerFactor","clusterUtilization","embodiedKgPerMtok","trainingKgPerMtok","activityUncertaintyPct","emissionFactorUncertaintyPct","createdAt"]},"CarbonFactorSet":{"type":"object","properties":{"version":{"type":"string","example":"v1.2"},"active":{"type":"boolean","description":"True when this is the version the pipeline currently writes with."},"layered":{"type":"boolean","description":"True when the version carries the v1.2 layered-emissions factors."},"factors":{"type":"array","items":{"$ref":"#/components/schemas/CarbonFactor"}}},"required":["version","active","layered","factors"]},"PublicTotalTokens":{"type":"object","properties":{"totalTokens":{"type":"number","description":"Cumulative tokens tracked across all organizations, all time.","example":1284930571}},"required":["totalTokens"]},"PublicEmissionsEstimate":{"type":"object","properties":{"energyJoules":{"type":"number"},"energyKwh":{"type":"number"},"co2Kg":{"type":"number"},"co2LowerBoundKg":{"type":"number"},"co2UpperBoundKg":{"type":"number"},"waterLiters":{"type":"number"},"waterLowerBoundL":{"type":"number"},"waterUpperBoundL":{"type":"number"},"waterFactorsVersion":{"type":"string"},"modelTier":{"type":"string"},"pue":{"type":"number"},"gridIntensity":{"type":"number"},"uncertaintyPct":{"type":"number"},"factorsVersion":{"type":"string"}},"required":["energyJoules","energyKwh","co2Kg","co2LowerBoundKg","co2UpperBoundKg","waterLiters","waterLowerBoundL","waterUpperBoundL","waterFactorsVersion","modelTier","pue","gridIntensity","uncertaintyPct","factorsVersion"]},"PublicEmissionsEstimateRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"maxLength":200,"description":"Model id matched against carbon_factors exactly like the worker ingestion path.","example":"gpt-4o-mini"},"inputTokensUncached":{"type":"integer","minimum":0,"default":0,"example":1000},"inputTokensCached":{"type":"integer","minimum":0,"default":0,"example":0},"inputTokensCacheCreation":{"type":"integer","minimum":0,"default":0,"example":0},"outputTokens":{"type":"integer","minimum":0,"default":0,"example":500}},"required":["model"]},"PublicShowcaseUsage":{"type":"object","properties":{"range":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"totals":{"type":"object","properties":{"totalTokens":{"type":"number"},"inputTokens":{"type":"number","description":"Uncached + cached + cache-creation input tokens."},"outputTokens":{"type":"number"},"requestCount":{"type":"number"},"carbonKg":{"type":"number"},"electricityKwh":{"type":"number"},"waterLiters":{"type":"number","description":"Estimated water footprint in liters. ESTIMATE ONLY."},"waterLowerBoundL":{"type":"number","description":"Lower uncertainty bound of the water estimate (liters)."},"waterUpperBoundL":{"type":"number","description":"Upper uncertainty bound of the water estimate (liters)."}},"required":["totalTokens","inputTokens","outputTokens","requestCount","carbonKg","electricityKwh","waterLiters","waterLowerBoundL","waterUpperBoundL"]},"avgDailyTokens":{"type":"number","description":"totalTokens over the number of days in the range."},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"UTC day, YYYY-MM-DD."},"totalTokens":{"type":"number"},"inputTokens":{"type":"number"},"outputTokens":{"type":"number"},"carbonKg":{"type":"number"},"electricityKwh":{"type":"number"},"waterLiters":{"type":"number"}},"required":["date","totalTokens","inputTokens","outputTokens","carbonKg","electricityKwh","waterLiters"]}},"byProvider":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"totalTokens":{"type":"number"},"pct":{"type":"number","description":"Share of the range totalTokens, one decimal, 0–100."}},"required":["provider","totalTokens","pct"]}},"methodology":{"type":"object","properties":{"factorsVersion":{"type":"string","example":"v1.2"},"framework":{"type":"string"}},"required":["factorsVersion","framework"]},"computedAt":{"type":"string","description":"ISO-8601; when the backend computed this payload."}},"required":["range","totals","avgDailyTokens","daily","byProvider","methodology","computedAt"]},"PublicOpenRouterUsage":{"type":"object","properties":{"asOf":{"type":"string","description":"YYYY-MM-DD of the last successful dataset sync."},"coverageEnd":{"type":"string","description":"YYYY-MM-DD; the last day the dataset covered at the last sync. Months whose last day is after this are served as partial."},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"Calendar month, YYYY-MM (UTC)."},"tokens":{"type":"number"},"partial":{"type":"boolean","description":"Present and true only for a month the dataset had not fully covered."}},"required":["month","tokens"]}},"byMonth":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"total":{"type":"number"},"providers":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tokens":{"type":"number"},"pct":{"type":"number"}},"required":["slug","name","tokens","pct"]}},"models":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","description":"OpenRouter permaslug, e.g. deepseek/deepseek-v4-flash-20260731."},"name":{"type":"string"},"provider":{"type":"string"},"providerSlug":{"type":"string"},"version":{"type":"string","description":"ISO date of the model version, when the permaslug carries one."},"free":{"type":"boolean"},"tokens":{"type":"number"},"pct":{"type":"number"}},"required":["slug","name","provider","providerSlug","free","tokens","pct"]}}},"required":["month","total","providers","models"]}},"sourceUrl":{"type":"string"},"computedAt":{"type":"string","description":"ISO-8601; when the backend computed this payload."}},"required":["asOf","coverageEnd","months","byMonth","sourceUrl","computedAt"]}}},"paths":{"/api/v1/projects":{"get":{"operationId":"projects.list","tags":["Projects"],"summary":"List projects","description":"Lists projects in the active organization. With `?include=usage`, returns per-project connection count + last-30d CO₂ rollup.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["usage"]},"required":false,"name":"include","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Projects list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"projects":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/ProjectPublic"}},{"type":"array","items":{"$ref":"#/components/schemas/ProjectWithUsage"}}]}},"required":["projects"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/usage/summary":{"get":{"operationId":"usage.getSummary","tags":["Usage"],"summary":"Get usage summary","description":"Returns totals (tokens/cost/carbon/energy/offset) plus a daily chart for the requested date range, optionally scoped to a project. Supply `startDate` + `endDate` (YYYY-MM-DD, together, max 366 days) for a custom period; they take precedence over `range`.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["7d","30d","90d","365d"],"default":"30d"},"required":false,"name":"range","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"endDate","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/UsageSummary"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/usage/breakdown":{"get":{"operationId":"usage.getBreakdown","tags":["Usage"],"summary":"Get per-model breakdown","description":"Returns per-model token/cost/carbon/energy rollups (with `percentage` share of total tokens) for the requested date range, optionally scoped to a project. Supply `startDate` + `endDate` (YYYY-MM-DD, together, max 366 days) for a custom period; they take precedence over `range`.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["7d","30d","90d","365d"],"default":"30d"},"required":false,"name":"range","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"endDate","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Per-model breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageBreakdownItem"}}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/usage/daily":{"get":{"operationId":"usage.getDaily","tags":["Usage"],"summary":"Get daily aggregates","description":"Returns flat daily token/cost/carbon rows for the requested date range, optionally scoped to a project. Supply `startDate` + `endDate` (YYYY-MM-DD, together, max 366 days) for a custom period; they take precedence over `range`.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["7d","30d","90d","365d"],"default":"30d"},"required":false,"name":"range","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"endDate","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Daily aggregates","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DailyUsageRow"}}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/usage/export":{"get":{"operationId":"usage.exportDaily","tags":["Usage"],"summary":"Export daily aggregates as CSV or JSON","description":"Returns a downloadable file (CSV uses RFC-4180 quoting; JSON is a flat array — no envelope). The `format` query selects the content type. When `projectId` is set, every row carries that project's name in the `project_name` column. Supply `startDate` + `endDate` (YYYY-MM-DD, together, max 366 days) for a custom period; the filename then reflects those bounds instead of the preset.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["7d","30d","90d","365d"],"default":"30d"},"required":false,"name":"range","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"endDate","in":"query"},{"schema":{"type":"string","enum":["csv","json"],"default":"csv"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"projectId","in":"query"}],"responses":{"200":{"description":"Exported file (CSV or JSON depending on `format` param)","content":{"text/csv":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DailyUsageExportRow"}}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/telemetry/summary":{"get":{"operationId":"telemetry.getSummary","tags":["Telemetry"],"summary":"Get telemetry summary","description":"Returns CO2 totals (with upper/lower bounds), cached-vs-uncached token split, per-model rollups, and a daily chart for the requested date range, optionally scoped to a project.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"start_date","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"required":false,"name":"end_date","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"project_id","in":"query"}],"responses":{"200":{"description":"Telemetry summary","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/TelemetrySummary"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/telemetry/models":{"get":{"operationId":"telemetry.listModels","tags":["Telemetry"],"summary":"List distinct telemetry models","description":"Returns the set of distinct provider/model pairs seen in the org with total tokens, total CO2, event count, and first/last-seen timestamps.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Distinct models","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/TelemetryModel"}}},"required":["models"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/retirement-status":{"get":{"operationId":"billing.getRetirementStatus","tags":["Billing"],"summary":"Get carbon retirement status","description":"Customer-facing snapshot of the current billing period's carbon-retirement lifecycle: a translated status (collecting → calculating → awaiting_payment → retiring → retired / pending_signature / action_required), the period's carbon + electricity totals, the amount charged, and a receipt summary (null until credits are retired). Scoped to the authenticated organization. 404 when the org has no periods yet.","security":[{"bearerAuth":[]},{"apiKey":[]}],"responses":{"200":{"description":"Current retirement status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"retirementStatus":{"$ref":"#/components/schemas/RetirementStatus"}},"required":["retirementStatus"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/receipts":{"get":{"operationId":"billing.listReceipts","tags":["Billing"],"summary":"List billing periods with their carbon receipt and statement","description":"Paginated, billing-period-driven list: one entry per closed period that has a carbon receipt or a footprint statement. `receipt` is null when the period retired no carbon; `statementId` links its footprint statement. Paywalled: free-tier orgs receive 402 PAYMENT_REQUIRED with an `upgradeUrl`.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated billing-period receipt entries","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReceiptListEntry"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success","data","pagination"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required — feature gated behind paid tier; clients should redirect to upgradeUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/receipts/{id}":{"get":{"operationId":"billing.getReceipt","tags":["Billing"],"summary":"Get a carbon receipt","description":"Returns a single receipt by id, scoped to the caller's organization. Paywalled.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000001"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Carbon receipt","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/CarbonReceipt"}},"required":["receipt"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required — feature gated behind paid tier; clients should redirect to upgradeUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/statements":{"get":{"operationId":"billing.listStatements","tags":["Billing"],"summary":"List footprint statements","description":"Paginated list of the org's prepared or Trust-signed footprint statements, newest first. Paywalled: free-tier orgs receive 402 PAYMENT_REQUIRED with an `upgradeUrl`.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated footprint statements","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/TrustSignedStatement"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success","data","pagination"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required — feature gated behind paid tier; clients should redirect to upgradeUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/statements/{id}":{"get":{"operationId":"billing.getStatement","tags":["Billing"],"summary":"Get a footprint statement","description":"Returns the prepared or Trust-signed footprint statement for the statementId returned by the receipt list. It is scoped to the authenticated organization and includes close-time usage, footprint totals, and Trust links when signed. Paywalled.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000001"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Footprint statement","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"statement":{"$ref":"#/components/schemas/TrustSignedStatement"}},"required":["statement"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required — feature gated behind paid tier; clients should redirect to upgradeUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/audit-packs":{"get":{"operationId":"billing.listAuditPacks","tags":["Billing"],"summary":"List audit packs","description":"Paginated list of generated audit packs (one per month, ZIP exports of receipts + manifest). Paywalled.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Paginated audit packs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditPack"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success","data","pagination"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required — feature gated behind paid tier; clients should redirect to upgradeUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/audit-packs/{id}":{"get":{"operationId":"billing.getAuditPack","tags":["Billing"],"summary":"Get an audit pack","description":"Returns a single audit pack by id, scoped to the caller's organization. Paywalled.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"00000000-0000-0000-0000-000000000001"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Audit pack","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"auditPack":{"$ref":"#/components/schemas/AuditPack"}},"required":["auditPack"]}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required — feature gated behind paid tier; clients should redirect to upgradeUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/carbon-factors":{"get":{"operationId":"carbonFactors.list","tags":["Factors"],"summary":"List carbon factor versions","description":"Returns every emissions factor version, oldest first, with whether it is the active writer version and whether it carries the v1.2 layered-emissions factors.","security":[{"bearerAuth":[]},{"apiKey":[]}],"responses":{"200":{"description":"Factor versions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CarbonFactorVersionList"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Factor configuration is inconsistent or the active version is not seeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/carbon-factors/current":{"get":{"operationId":"carbonFactors.getCurrent","tags":["Factors"],"summary":"Get the active carbon factor set","description":"Returns the factor set the pipeline currently writes new calculations with. Responds 503 if that version is not seeded, rather than falling back to another version.","security":[{"bearerAuth":[]},{"apiKey":[]}],"responses":{"200":{"description":"Active factor set","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CarbonFactorSet"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Factor configuration is inconsistent or the active version is not seeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/carbon-factors/{version}":{"get":{"operationId":"carbonFactors.getByVersion","tags":["Factors"],"summary":"Get one carbon factor version","description":"Returns the full factor set for a specific version, e.g. `v1.1`.","security":[{"bearerAuth":[]},{"apiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":20,"pattern":"^v\\d+\\.\\d+$","example":"v1.2"},"required":true,"name":"version","in":"path"}],"responses":{"200":{"description":"Factor set for the version","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CarbonFactorSet"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Factor configuration is inconsistent or the active version is not seeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/public/total-tokens":{"get":{"operationId":"publicStats.getTotalTokens","tags":["Usage"],"summary":"Get cumulative tokens tracked","description":"Returns the platform-wide cumulative token total across every organization, all time. No auth required — powers the public landing page counter. Cached for 60 seconds.","security":[],"responses":{"200":{"description":"Cumulative token total","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PublicTotalTokens"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/public/emissions-estimate":{"post":{"operationId":"publicStats.estimateEmissions","tags":["Usage"],"summary":"Estimate CO2e, electricity, and water from token buckets","description":"Runs the exact same factor-resolution and emissions math path the worker uses before writing carbon_calculations. Accepts a model id plus token buckets and returns CO2e, electricity, and water estimates with the same metadata fields the worker persists.","security":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicEmissionsEstimateRequest"}}}},"responses":{"200":{"description":"Emissions estimate","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PublicEmissionsEstimate"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/public/usage/crbonlabs":{"get":{"operationId":"publicUsage.getCrbonLabs","tags":["Usage"],"summary":"Crbon Labs' own AI usage footprint","description":"Aggregate AI usage and emissions for Crbon Labs Inc.'s own organisation over a trailing window — the same numbers the product dashboard shows, to the token. Aggregates only: no events, users, keys, connections or cost. No auth required — powers the public landing and case study. Cached for 30 minutes; `computedAt` is when the payload was computed.","security":[],"parameters":[{"schema":{"type":"string","enum":["7d","30d","90d","365d"],"default":"365d","description":"Trailing window in UTC days — the same presets GET /api/v1/usage/summary accepts.","example":"365d"},"required":false,"name":"range","in":"query"}],"responses":{"200":{"description":"Showcase usage","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PublicShowcaseUsage"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Not available — showcase organisation not configured, or the OpenRouter dataset has not been synced yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/public/usage/openrouter":{"get":{"operationId":"publicUsage.getOpenRouter","tags":["Usage"],"summary":"OpenRouter public usage series","description":"Monthly token totals from OpenRouter's public rankings dataset (https://openrouter.ai/rankings), with the provider share stack and top models for every complete month. Synced daily by the backend. No auth required. Cached for 30 minutes; `asOf` is the last successful sync, `computedAt` when the payload was computed.","security":[],"responses":{"200":{"description":"OpenRouter series","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PublicOpenRouterUsage"}},"required":["success","data"]}}}},"400":{"description":"Bad request — validation failed or malformed JSON body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — token missing, expired, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until next request allowed"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Not available — showcase organisation not configured, or the OpenRouter dataset has not been synced yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}