{"openapi":"3.1.0","info":{"title":"CarbonTrace API","version":"1.0.0","description":"Full lifecycle carbon footprint calculations for IT hardware. PAIA-aligned methodology, calibrated within ±5% of manufacturer-published PCFs. Covers production, transport, use-phase, and end-of-life for 48 IT device categories across 266 countries and sub-national regions.","contact":{"name":"CarbonTrace Support","url":"https://carbontrace.cloud","email":"support@carbontrace.cloud"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://carbontrace.cloud/api/v1","description":"Production"}],"security":[{},{"bearerAuth":[]}],"tags":[{"name":"Footprint","description":"Calculate lifecycle carbon footprints for IT devices"},{"name":"Products","description":"Search and identify products via built-in database and Icecat"},{"name":"Certificates","description":"Generate and download verifiable CO₂ impact certificates"},{"name":"Reports","description":"Generate sustainability and hotspot analysis PDF reports"},{"name":"Reference","description":"Countries, grid factors, and device categories"},{"name":"Integrations","description":"Third-party platform integrations (Blancco)"},{"name":"Export","description":"Async org-wide GDPR bulk export jobs"},{"name":"BI Export","description":"OData v4 read-only endpoint for Power BI, Tableau, and Excel. Enterprise-only. Every response is signed with a hash-linked proof header tied to the CarbonTrace audit log. See /docs/bi-export for setup instructions."}],"paths":{"/footprint":{"get":{"operationId":"calculateFootprint","summary":"Calculate carbon footprint","description":"Calculate the full lifecycle carbon footprint for a single IT device. The engine attempts Icecat product lookup first; if the product is not found, it falls back to parametric estimation using provided specs or category defaults.","tags":["Footprint"],"parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string"},"description":"Manufacturer name (e.g. HP, Dell, Apple, Lenovo)","example":"Apple"},{"name":"mpn","in":"query","schema":{"type":"string"},"description":"Manufacturer Part Number. Either `mpn` or `model` is required.","example":"MacBookPro18,1"},{"name":"model","in":"query","schema":{"type":"string"},"description":"Model name (alternative to mpn). Either `mpn` or `model` is required.","example":"MacBook Pro 14"},{"name":"country","in":"query","required":true,"schema":{"type":"string"},"description":"ISO 3166-1 alpha-2 country code for grid emission factor","example":"NL"},{"name":"category","in":"query","schema":{"type":"string","default":"laptop"},"description":"Device category (used as fallback when Icecat lookup fails)","example":"laptop"},{"name":"weight_kg","in":"query","schema":{"type":"number"},"description":"Device weight in kg (overrides default)"},{"name":"tdp","in":"query","schema":{"type":"number"},"description":"Processor TDP in watts"},{"name":"ram_gb","in":"query","schema":{"type":"number"},"description":"RAM capacity in GB"},{"name":"battery_wh","in":"query","schema":{"type":"number"},"description":"Battery capacity in Wh"},{"name":"screen_size_inch","in":"query","schema":{"type":"number"},"description":"Screen diagonal in inches"},{"name":"screen_type","in":"query","schema":{"type":"string","enum":["lcd","oled","ips","tn","va","mini_led"]},"description":"Display technology"},{"name":"storage_gb","in":"query","schema":{"type":"number"},"description":"Storage capacity in GB"},{"name":"storage_type","in":"query","schema":{"type":"string","enum":["ssd","hdd","emmc","nvme"]},"description":"Storage technology"}],"responses":{"200":{"description":"Successful calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarbonFootprint"}}},"headers":{"Cache-Control":{"schema":{"type":"string"},"description":"public, max-age=86400"},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request limit for your plan"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests today"},"X-RateLimit-Plan":{"schema":{"type":"string"},"description":"Your current plan tier"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/footprint/batch":{"post":{"operationId":"batchCalculateFootprint","summary":"Batch calculate footprints","description":"Calculate carbon footprints for up to 100 products in a single request. Each product is calculated independently — failures for individual items don't affect others.","tags":["Footprint"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["products"],"properties":{"products":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/FootprintRequest"},"description":"Array of products to calculate (max 100)"}}},"example":{"products":[{"brand":"HP","mpn":"2E4L2EA","country":"BE"},{"brand":"Dell","model":"Latitude 5540","country":"NL"}]}}}},"responses":{"200":{"description":"Batch results (may include per-item errors)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/savings":{"get":{"operationId":"calculateReuseSavings","summary":"Calculate reuse savings","description":"Calculate the CO₂ avoided by extending a device's life through reuse, compared to manufacturing a new one. Returns avoided emissions, equivalents (km driving, tree years), and the additional use-phase cost.","tags":["Footprint"],"parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string"},"example":"HP"},{"name":"mpn","in":"query","schema":{"type":"string"},"description":"Either `mpn` or `model` is required.","example":"2E4L2EA"},{"name":"model","in":"query","schema":{"type":"string"},"description":"Either `mpn` or `model` is required."},{"name":"country","in":"query","required":true,"schema":{"type":"string"},"example":"BE"},{"name":"remaining_years","in":"query","schema":{"type":"number","default":2},"description":"Expected remaining useful life in years"},{"name":"category","in":"query","schema":{"type":"string","default":"laptop"},"description":"Fallback device category"},{"name":"weight_kg","in":"query","schema":{"type":"number"}},{"name":"tdp","in":"query","schema":{"type":"number"}},{"name":"ram_gb","in":"query","schema":{"type":"number"}},{"name":"storage_gb","in":"query","schema":{"type":"number"}},{"name":"storage_type","in":"query","schema":{"type":"string","enum":["ssd","hdd","emmc","nvme"]}},{"name":"battery_wh","in":"query","schema":{"type":"number"}},{"name":"screen_size_inch","in":"query","schema":{"type":"number"}},{"name":"screen_type","in":"query","schema":{"type":"string","enum":["lcd","oled","ips","tn","va","mini_led"]}}],"responses":{"200":{"description":"Reuse savings calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReuseSavings"}}},"headers":{"Cache-Control":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/refurbishment":{"get":{"operationId":"calculateRefurbishment","summary":"Calculate refurbishment impact","description":"Calculate the net CO₂ savings from refurbishing a device vs buying new. Supports grade-based overhead (A/B/C) and individual component swap costing. Returns detailed breakdown including refurbishment overhead, component swap costs, adjusted use-phase, net savings, break-even years, and a production component heatmap.","tags":["Footprint"],"parameters":[{"name":"brand","in":"query","required":true,"schema":{"type":"string"},"example":"HP"},{"name":"mpn","in":"query","schema":{"type":"string"},"description":"Either `mpn` or `model` is required.","example":"EliteBook 840 G10"},{"name":"model","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","required":true,"schema":{"type":"string"},"example":"BE"},{"name":"grade","in":"query","required":true,"schema":{"type":"string","enum":["A","B","C"]},"description":"Refurbishment condition grade. A=Like New, B=Good, C=Fair."},{"name":"remaining_years","in":"query","schema":{"type":"number","default":2},"description":"Expected remaining useful life after refurbishment"},{"name":"reuse_country","in":"query","schema":{"type":"string"},"description":"Country where refurbished device will be used (different grid factor). Defaults to `country`."},{"name":"swaps","in":"query","schema":{"type":"string"},"description":"Comma-separated component swaps. Format: `battery:56,storage:512:nvme,ram:8:16,display:14:ips,keyboard_trackpad`","example":"battery:56,storage:512:nvme"},{"name":"category","in":"query","schema":{"type":"string","default":"laptop"}},{"name":"weight_kg","in":"query","schema":{"type":"number"}},{"name":"tdp","in":"query","schema":{"type":"number"}},{"name":"ram_gb","in":"query","schema":{"type":"number"}},{"name":"storage_gb","in":"query","schema":{"type":"number"}},{"name":"storage_type","in":"query","schema":{"type":"string","enum":["ssd","hdd","emmc","nvme"]}},{"name":"battery_wh","in":"query","schema":{"type":"number"}},{"name":"screen_size_inch","in":"query","schema":{"type":"number"}},{"name":"screen_type","in":"query","schema":{"type":"string","enum":["lcd","oled","ips","tn","va","mini_led"]}}],"responses":{"200":{"description":"Refurbishment impact calculation with grade overhead, swap costs, net savings, and break-even analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefurbishmentResult"}}},"headers":{"Cache-Control":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/search":{"get":{"operationId":"searchProducts","summary":"Search product database","description":"Fuzzy-search the built-in database of 435+ IT devices. Returns up to 15 results with full specs.","tags":["Products"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Search query (min 2 characters)","example":"macbook pro"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/identify":{"post":{"operationId":"identifyProduct","summary":"Identify product via Icecat","description":"Look up a product by manufacturer and model string in the Icecat database. Returns normalized specs if found. Useful for resolving asset management exports into CarbonTrace-compatible specs.","tags":["Products"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"manufacturer":{"type":"string","description":"Manufacturer name (alias: `brand`)"},"model_string":{"type":"string","description":"Model identifier (alias: `mpn`)"},"brand":{"type":"string","description":"Alias for manufacturer"},"mpn":{"type":"string","description":"Alias for model_string"}}},"example":{"manufacturer":"LENOVO","model_string":"20Y7S0BN00"}}}},"responses":{"200":{"description":"Product identified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Product not found in Icecat","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean","const":false},"brand":{"type":"string"},"mpn":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/certificate":{"post":{"operationId":"createCertificate","summary":"Generate certificate","description":"Create a verifiable CO₂ impact certificate from an existing calculation. Requires authentication (session-based). Returns certificate metadata with download and verification URLs.","tags":["Certificates"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["calculation_id"],"properties":{"calculation_id":{"type":"string","format":"uuid","description":"ID of an existing calculation in your organization"}}},"example":{"calculation_id":"550e8400-e29b-41d4-a716-446655440000"}}}},"responses":{"200":{"description":"Certificate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Calculation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"downloadCertificate","summary":"Download certificate PDF","description":"Download a previously generated certificate as a PDF document.","tags":["Certificates"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"Certificate ID"}],"responses":{"200":{"description":"Certificate PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Certificate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/report":{"post":{"operationId":"generateReport","summary":"Generate PDF report","description":"Generate a sustainability summary or hotspot analysis PDF report. Requires authentication and Pro plan or higher. Free plan returns 403.","tags":["Reports"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["sustainability_summary","hotspot_analysis"],"description":"Report type"},"dateFrom":{"type":"string","format":"date","description":"Start date filter (YYYY-MM-DD)"},"dateTo":{"type":"string","format":"date","description":"End date filter (YYYY-MM-DD)"}}},"example":{"type":"sustainability_summary","dateFrom":"2025-01-01","dateTo":"2025-12-31"}}}},"responses":{"200":{"description":"Report PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Pro plan or higher required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Monthly report limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/blancco/sync":{"post":{"operationId":"syncBlancco","summary":"Sync Blancco reports","description":"Fetch new erasure reports from Blancco Management Console, parse device specs, and calculate carbon footprints. Requires an API key with organization context. Reports already processed are automatically skipped.","tags":["Integrations"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"onlySuccessful":{"type":"boolean","description":"Only sync reports with successful erasure"},"sinceDate":{"type":"string","format":"date","description":"Only sync reports after this date"},"country":{"type":"string","default":"NL","description":"Country code for footprint calculation (default: NL)"}}},"example":{"onlySuccessful":true,"country":"NL"}}}},"responses":{"200":{"description":"Sync results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlanccoSyncResult"}}}},"403":{"description":"Organization context required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/reference/countries":{"get":{"operationId":"listCountries","summary":"List countries & grid factors","description":"List all 266 supported countries and sub-national regions with their grid emission factors (kg CO₂e/kWh). Includes 212 countries and 54 sub-national regions (US states, Chinese provinces).","tags":["Reference"],"responses":{"200":{"description":"Country list","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","example":266},"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"NL"},"grid_factor":{"type":"number","description":"kg CO₂e per kWh","example":0.386}}}}}}}},"headers":{"Cache-Control":{"schema":{"type":"string"},"description":"public, max-age=604800"}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/reference/categories":{"get":{"operationId":"listCategories","summary":"List device categories","description":"List all 48 supported IT device categories with their default lifetime and annual energy consumption assumptions.","tags":["Reference"],"responses":{"200":{"description":"Category list","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","example":48},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","example":"laptop"},"lifetime_years":{"type":"number","example":4},"fallback_kwh_per_year":{"type":"number","example":30}}}}}}}},"headers":{"Cache-Control":{"schema":{"type":"string"},"description":"public, max-age=604800"}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/org/export/jobs":{"post":{"operationId":"submitOrgExport","summary":"Submit org-wide bulk export","description":"Start an async job that produces a ZIP containing every org-owned row across 22 tables (organizations, profiles, assets, calculations, certificates, audit_log, etc.), plus a manifest with per-file SHA-256 and a README explaining the N135 Asset Inventory semantics. GDPR Article 20 compliant: structured, commonly used, machine-readable. The ZIP is uploaded to a private bucket and fetched via `/org/export/jobs/{id}/download` using a short-lived signed URL. Rate-limited per plan: Free 30 days, Pro 7 days, Business 24 hours, Enterprise 1 hour. Exactly one job can be in flight per org (second attempt returns 429 TOO_MANY_ACTIVE_EXPORTS). Supports `Idempotency-Key` header (time-bucketed per day). Secrets `api_keys.key` and `webhook_endpoints.secret` are null-redacted.","tags":["Export"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Client-provided token. Repeating the same key within 24h returns the existing job instead of creating a new one."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"object","description":"Optional table filter. Default: include all 22 tables.","properties":{"include":{"type":"array","items":{"type":"string"},"description":"Whitelist of table names."},"exclude":{"type":"array","items":{"type":"string"},"description":"Blacklist applied after include."}}},"format":{"type":"string","enum":["zip"],"default":"zip"}}}}}},"responses":{"202":{"description":"Job submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportJobSubmit"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"get":{"operationId":"listOrgExports","summary":"List recent export jobs","description":"Returns the authenticated org's export jobs from the last 30 days (most recent first). Limit 50 per page.","tags":["Export"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Paginated job list","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"jobs":{"type":"array","items":{"$ref":"#/components/schemas/ExportJob"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/org/export/jobs/{id}":{"get":{"operationId":"getOrgExportJob","summary":"Poll export job status","description":"Returns the full job row: status, scope, total tables/rows, bytes, sha256, manifest, and error details if failed. Poll this until `status` is `completed`, then call `/download`.","tags":["Export"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportJob"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"cancelOrgExportJob","summary":"Cancel a pending/processing export job","description":"Only jobs in `pending` or `processing` status can be cancelled. If a partial storage object exists it is deleted.","tags":["Export"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelled"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Job is not in a cancellable state"}}}},"/org/export/jobs/{id}/download":{"get":{"operationId":"downloadOrgExport","summary":"Get a signed download URL for a completed export","description":"Verifies org ownership, writes an `org.export.job.downloaded` audit event, and either 302-redirects to a 15-minute signed URL or returns `{ signed_url, expires_at }` JSON if the client sends `Accept: application/json`. Returns 409 if the job is not yet `completed`, 410 if the 72-hour TTL has expired.","tags":["Export"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"JSON with signed URL (when Accept: application/json)","content":{"application/json":{"schema":{"type":"object","properties":{"signed_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"bytes":{"type":"integer"},"sha256":{"type":"string"}}}}}},"302":{"description":"Redirect to short-lived signed URL (15 min TTL)"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Job not yet completed"},"410":{"description":"Export expired (72h TTL)"}}}},"/odata/$metadata":{"get":{"operationId":"odataMetadata","summary":"OData v4 service metadata (CSDL XML)","description":"Returns the Entity Data Model in OData v4 CSDL XML format. Power BI, Tableau, and Excel auto-discover entity sets via this endpoint when you point them at the base OData URL. Requires an API key with `bi_enabled=true` on an Enterprise-plan organization.","tags":["BI Export"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"CSDL XML document","content":{"application/xml":{"schema":{"type":"string","format":"xml"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"BI export not enabled on this API key"},"403":{"description":"Enterprise plan required"}}}},"/odata/{EntitySet}":{"get":{"operationId":"odataEntityQuery","summary":"Query an OData entity set","description":"Query one of the exposed entity sets with OData v4 query options. Supported entity sets: `Assets`, `Certificates`, `Products`, `EmissionFactors`, `SbtiTargets`, `MonthlyEmissions`. Every response carries forensic proof headers (`X-CarbonTrace-Proof`, `X-CarbonTrace-Proof-Hash`, `X-CarbonTrace-Data-Freshness`) tying the result to a row in the CarbonTrace audit log. Unsupported operators return `501 Not Implemented` with the list of supported options in the body.","tags":["BI Export"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"EntitySet","in":"path","required":true,"schema":{"type":"string","enum":["Assets","Certificates","Products","EmissionFactors","SbtiTargets","MonthlyEmissions"]},"description":"Entity set name (case-insensitive)"},{"name":"$top","in":"query","schema":{"type":"integer","default":1000,"maximum":5000},"description":"Maximum number of rows to return"},{"name":"$skip","in":"query","schema":{"type":"integer","default":0},"description":"Number of rows to skip (pagination)"},{"name":"$count","in":"query","schema":{"type":"boolean","default":false},"description":"Include the total row count as `@odata.count`"},{"name":"$select","in":"query","schema":{"type":"string"},"description":"Comma-separated list of properties to return","example":"asset_id,brand,mpn,total_kg_co2e"},{"name":"$orderby","in":"query","schema":{"type":"string"},"description":"Sort expression","example":"purchase_date desc"},{"name":"$filter","in":"query","schema":{"type":"string"},"description":"Boolean expression using eq, ne, gt, ge, lt, le, and, or plus startswith(), contains(), endswith(). Unsupported operators return HTTP 501.","example":"category eq 'laptop' and country eq 'BE'"}],"responses":{"200":{"description":"OData v4 result document","content":{"application/json":{"schema":{"type":"object","properties":{"@odata.context":{"type":"string"},"@odata.count":{"type":"integer"},"value":{"type":"array","items":{"type":"object"}}}}}},"headers":{"X-CarbonTrace-Proof":{"description":"ID of the audit_log row recording this query","schema":{"type":"string"}},"X-CarbonTrace-Proof-Hash":{"description":"SHA256 of the returned rows (deterministic)","schema":{"type":"string"}},"X-CarbonTrace-Data-Freshness":{"description":"ISO timestamp of the latest underlying update","schema":{"type":"string","format":"date-time"}}}},"400":{"description":"Invalid query option (e.g. unknown column in $filter)"},"401":{"description":"Missing or invalid API key"},"402":{"description":"BI export not enabled on this API key"},"403":{"description":"Enterprise plan required"},"404":{"description":"Unknown entity set"},"429":{"$ref":"#/components/responses/RateLimited"},"501":{"description":"Unsupported OData operator"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key starting with `ct_`. Get one at https://carbontrace.cloud/api-keys. Open endpoints work without a key at free-tier limits (25 requests/day)."}},"schemas":{"CarbonFootprint":{"type":"object","properties":{"product":{"type":"object","properties":{"brand":{"type":"string","example":"Apple"},"mpn":{"type":"string","example":"MacBookPro18,1"},"name":{"type":"string","example":"MacBook Pro 14-inch (2021)"},"category":{"type":"string","example":"laptop"},"weight_kg":{"type":"number","example":1.6}}},"country":{"type":"string","example":"NL"},"total_kg_co2e":{"type":"number","description":"Total lifecycle carbon footprint in kg CO₂e","example":271.4},"breakdown":{"$ref":"#/components/schemas/CarbonBreakdown"},"methodology":{"type":"object","properties":{"standard":{"type":"string","example":"PAIA-aligned parametric model"},"data_sources":{"type":"array","items":{"type":"string"},"example":["Icecat specs","ADEME Base Carbone","EU JRC grid factors"]},"confidence":{"type":"string","enum":["manufacturer_verified","estimated_high","estimated_medium","estimated_low"],"example":"estimated_high"},"uncertainty_pct":{"type":"number","description":"Uncertainty range in percent","example":15}}},"calculated_at":{"type":"string","format":"date-time"}}},"CarbonBreakdown":{"type":"object","description":"CO₂e breakdown by lifecycle phase (kg)","properties":{"production_kg":{"type":"number","example":185.2},"transport_kg":{"type":"number","example":12.8},"use_phase_kg":{"type":"number","example":69.4},"end_of_life_kg":{"type":"number","example":4}}},"ReuseSavings":{"type":"object","properties":{"product":{"type":"object","properties":{"brand":{"type":"string"},"mpn":{"type":"string"},"name":{"type":"string"}}},"country":{"type":"string"},"remaining_life_years":{"type":"number","example":2},"avoided_co2_kg":{"type":"number","description":"Net CO₂ avoided through reuse","example":162.8},"avoided_production_kg":{"type":"number","example":185.2},"avoided_transport_kg":{"type":"number","example":12.8},"additional_use_phase_kg":{"type":"number","description":"Extra use-phase emissions for remaining life","example":35.2},"equivalents":{"type":"object","properties":{"km_driving_avoided":{"type":"number","description":"Equivalent km of average car driving avoided","example":1085},"trees_year_equivalent":{"type":"number","description":"Equivalent tree-years of CO₂ absorption","example":7.4}}},"calculated_at":{"type":"string","format":"date-time"}}},"FootprintRequest":{"type":"object","required":["brand","country"],"properties":{"brand":{"type":"string"},"mpn":{"type":"string","description":"Either mpn or model required"},"model":{"type":"string","description":"Either mpn or model required"},"country":{"type":"string"},"category":{"type":"string"}}},"BatchResult":{"type":"object","properties":{"total":{"type":"integer","description":"Total products submitted"},"successful":{"type":"integer","description":"Successfully calculated"},"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/CarbonFootprint"},{"$ref":"#/components/schemas/BatchItemError"}]}}}},"BatchItemError":{"type":"object","properties":{"error":{"type":"string"},"index":{"type":"integer","description":"Index of the failed item in the input array"}}},"SearchResult":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer"},"source":{"type":"string","example":"built_in"},"results":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"mpn":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"release_year":{"type":"integer"},"specs":{"type":"object","properties":{"weight_kg":{"type":"number"},"screen_size_inch":{"type":"number"},"screen_type":{"type":"string"},"processor_tdp_w":{"type":"number"},"ram_gb":{"type":"number"},"storage_gb":{"type":"number"},"storage_type":{"type":"string"},"battery_wh":{"type":"number"},"typical_consumption_kwh":{"type":"number"}}}}}}}},"IdentifyResult":{"type":"object","properties":{"found":{"type":"boolean","const":true},"icecat_id":{"type":"integer"},"brand":{"type":"string"},"mpn":{"type":"string"},"name":{"type":"string"},"icecat_category":{"type":"string"},"mapped_category":{"type":"string"},"specs":{"type":"object","properties":{"weight_kg":{"type":"number"},"screen_size_inch":{"type":"number"},"screen_type":{"type":"string"},"processor_tdp_w":{"type":"number"},"ram_gb":{"type":"number"},"storage_gb":{"type":"number"},"storage_type":{"type":"string"},"battery_wh":{"type":"number"},"typical_consumption_kwh":{"type":"number"}}}}},"CertificateResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"certificate_number":{"type":"string","example":"CT-A1B2C3D4E5"},"issued_at":{"type":"string","format":"date-time"},"download_url":{"type":"string","format":"uri"},"verify_url":{"type":"string","format":"uri"}}},"BlanccoSyncResult":{"type":"object","properties":{"synced":{"type":"integer","description":"Reports successfully processed"},"skipped":{"type":"integer","description":"Reports already processed (deduplicated)"},"errors":{"type":"integer","description":"Reports that failed processing"},"details":{"type":"array","items":{"type":"object","properties":{"uuid":{"type":"string"},"status":{"type":"string","enum":["synced","skipped","error"]},"brand":{"type":"string"},"model":{"type":"string"},"error":{"type":"string"}}}}}},"ApiError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{"type":"string"}}},"RateLimitError":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string"},"retry_after_seconds":{"type":"integer"}}},"ExportJobSubmit":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled","expired"]},"created_at":{"type":"string","format":"date-time"},"poll_url":{"type":"string","example":"/api/v1/org/export/jobs/<id>"},"download_url":{"type":"string","example":"/api/v1/org/export/jobs/<id>/download"}}},"ExportJob":{"type":"object","description":"N88 org-wide bulk export job row.","properties":{"id":{"type":"string","format":"uuid"},"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed","cancelled","expired"]},"scope":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"}},"exclude":{"type":"array","items":{"type":"string"}}}},"format":{"type":"string","enum":["zip"]},"total_tables":{"type":"integer","nullable":true},"total_rows":{"type":"integer","nullable":true},"bytes":{"type":"integer","nullable":true},"sha256":{"type":"string","nullable":true,"description":"Hex SHA-256 of the whole ZIP"},"manifest":{"type":"object","nullable":true,"properties":{"schema_version":{"type":"string","enum":["1.0"]},"generated_at":{"type":"string","format":"date-time"},"org_id":{"type":"string","format":"uuid"},"software_version":{"type":"string"},"record_counts":{"type":"object","additionalProperties":{"type":"integer"}},"file_hashes":{"type":"object","additionalProperties":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}}}},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"72h after completion"},"poll_url":{"type":"string"},"download_url":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Unauthorized":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit resets"},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp of rate limit reset"}}},"ServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}