{"openapi":"3.1.0","info":{"title":"Mizani Carbon API","version":"1.0.0","description":"Kenya-first, source-traceable emission factors. Every value links to its source document, page, the script and commit that produced it, and an immutable release."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key: `Authorization: Bearer mzn_live_…`"},"userAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A signed-in dashboard user's Supabase access token (/v1/account only)."}},"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"latest_release":{"type":["string","null"],"example":"2026.1"}},"required":["status","latest_release"]},"Problem":{"type":"object","properties":{"type":{"type":"string","example":"/problems/unit-mismatch"},"title":{"type":"string","example":"Unit doesn't match the factor"},"status":{"type":"integer","example":422},"detail":{"type":"string","example":"ke.fuel.diesel.stationary is per kg or per litre; kWh is an energy unit."},"instance":{"type":"string","example":"/v1/estimate"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]},"description":"Field-level problems, for invalid requests."}},"required":["type","title","status"]},"FactorList":{"type":"object","properties":{"release":{"type":"string","example":"2026.1"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"factors":{"type":"array","items":{"$ref":"#/components/schemas/Factor"}}},"required":["release","page","per_page","total","factors"]},"Factor":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Stable id of this row in this release"},"factor_key":{"type":"string","example":"ke.fuel.diesel.stationary"},"release":{"type":"string","example":"2026.1"},"region":{"type":"string","example":"KE"},"sector":{"type":"string","example":"fuel"},"activity_unit":{"type":"string","example":"litre","description":"Values are kg per this unit"},"method":{"type":"string","enum":["official","derived"]},"period":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}},"required":["start","end"],"description":"Half-open validity period [start, end)","example":{"start":"2025-07-01","end":"2026-01-01"}},"data_year":{"type":"integer","example":2025},"gwp":{"type":"string","enum":["ar6","ar5"]},"values":{"type":"object","properties":{"co2":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"ch4":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"n2o":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"hfc":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"co2e":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$","description":"On the requested GWP basis; null when the source doesn't support it"},"biogenic_co2":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$","description":"Reported separately; never included in co2e"}},"required":["co2","ch4","n2o","hfc","co2e","biogenic_co2"],"description":"kg of each gas per activity unit. null means not reported, not zero.","example":{"co2":"0.1","ch4":null,"n2o":null,"hfc":null,"co2e":null,"biogenic_co2":null}},"quality_rating":{"type":["integer","null"]},"uncertainty":{"type":"object","properties":{"low":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"high":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"}},"required":["low","high"]},"provenance":{"type":"object","properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/CitedSource"}},"script_path":{"type":"string","example":"pipeline/extract/epra.ts;pipeline/build.ts"},"git_commit":{"type":"string","example":"0123456789abcdef0123456789abcdef01234567"}},"required":["sources","script_path","git_commit"]},"supersedes_id":{"type":["string","null"],"format":"uuid"},"citation":{"type":"string","description":"A sentence a report can paste","example":"ke.fuel.diesel.stationary per litre; derived from …; Mizani Carbon release 2026.1, factor 7b1c…"}},"required":["id","factor_key","release","region","sector","activity_unit","method","period","data_year","gwp","values","quality_rating","uncertainty","provenance","supersedes_id","citation"]},"CitedSource":{"allOf":[{"$ref":"#/components/schemas/Source"},{"type":"object","properties":{"pages":{"type":"array","items":{"type":"string"},"description":"PDF page indexes (or spreadsheet cells) where the inputs appear","example":["25"]}},"required":["pages"]}]},"Source":{"type":"object","properties":{"id":{"type":"string","example":"epra-biannual-fy2025-26"},"publisher":{"type":"string","example":"Energy and Petroleum Regulatory Authority (EPRA)"},"title":{"type":"string"},"url":{"type":"string","example":"https://www.epra.go.ke/sites/default/files/example.pdf"},"retrieved_on":{"type":"string","format":"date"},"sha256":{"type":"string","description":"SHA-256 of the file as downloaded"},"license_note":{"type":"string"}},"required":["id","publisher","title","url","retrieved_on","sha256","license_note"]},"FactorDetail":{"type":"object","properties":{"factor_key":{"type":"string","example":"ke.electricity.grid.location_based"},"release":{"type":"string"},"date":{"type":"string","format":"date"},"gwp":{"type":"string","enum":["ar6","ar5"]},"factors":{"type":"array","items":{"$ref":"#/components/schemas/Factor"},"description":"One row per activity unit (e.g. kg and litre)"}},"required":["factor_key","release","date","gwp","factors"]},"EstimateResult":{"type":"object","properties":{"factor_key":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","example":"100"},"unit":{"type":"string","example":"litre"},"date":{"type":"string","format":"date"},"gwp":{"type":"string","enum":["ar6","ar5"]},"co2e_kg":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$","description":"null when the factor has no CO2e on this basis; see notes"},"gases_kg":{"type":"object","properties":{"co2":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"ch4":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"n2o":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"},"hfc":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$"}},"required":["co2","ch4","n2o","hfc"]},"biogenic_co2_kg":{"type":["string","null"],"pattern":"^\\d+(\\.\\d+)?$","description":"Reported separately; not in co2e_kg"},"notes":{"type":"array","items":{"type":"string"}},"factor":{"$ref":"#/components/schemas/Factor"},"citation":{"type":"string","example":"ke.fuel.diesel.stationary per litre; sources: … ; Mizani Carbon release 2026.1, factor 7b1c…"}},"required":["factor_key","amount","unit","date","gwp","co2e_kg","gases_kg","biogenic_co2_kg","notes","factor","citation"]},"EstimateRequest":{"type":"object","properties":{"factor_key":{"type":"string","minLength":1,"example":"ke.fuel.diesel.stationary"},"amount":{"anyOf":[{"type":"string"},{"type":"number"}],"example":"100","description":"Non-negative decimal; a string keeps it exact"},"unit":{"type":"string","minLength":1,"example":"litre","description":"e.g. kWh, MWh, kg, t, litre, m3"},"date":{"type":"string","format":"date","example":"2025-09-15","description":"Date the activity happened"},"gwp":{"type":"string","enum":["ar6","ar5"],"default":"ar6","example":"ar6"},"release":{"type":"string","description":"Defaults to the latest release"}},"required":["factor_key","amount","unit","date"]},"EstimateBatchResult":{"type":"object","properties":{"results":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"result":{"$ref":"#/components/schemas/EstimateResult"}},"required":["ok","result"]},{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"problem":{"$ref":"#/components/schemas/Problem"}},"required":["ok","problem"]}]}}},"required":["results"]},"EstimateBatchRequest":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EstimateRequest"},"minItems":1,"maxItems":1000}},"required":["items"],"example":{"items":[{"factor_key":"ke.fuel.diesel.stationary","amount":"100","unit":"litre","date":"2025-09-15","gwp":"ar6"},{"factor_key":"ke.electricity.grid.location_based","amount":"2","unit":"MWh","date":"2025-09-15","gwp":"ar6"}]}},"Release":{"type":"object","properties":{"version":{"type":"string","example":"2026.1"},"published_at":{"type":"string","example":"2026-10-01T09:00:00.000Z"},"factor_count":{"type":"integer"}},"required":["version","published_at","factor_count"]},"ReleaseDetail":{"allOf":[{"$ref":"#/components/schemas/Release"},{"type":"object","properties":{"changelog_md":{"type":"string","example":"# Release 2026.1\n\n…"},"downloads":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseDownload"},"description":"The release as CSV and XLSX. Empty for releases published before downloads existed."},"fingerprint":{"$ref":"#/components/schemas/ReleaseFingerprint"},"attestations":{"type":"array","items":{"$ref":"#/components/schemas/ReleaseAttestation"},"description":"Public-chain attestations of the fingerprint, if any"}},"required":["changelog_md","downloads","fingerprint","attestations"]}]},"ReleaseDownload":{"type":"object","properties":{"format":{"type":"string","enum":["csv","xlsx"]},"filename":{"type":"string","example":"mizani-2026.1.csv"},"media_type":{"type":"string","example":"text/csv; charset=utf-8"},"bytes":{"type":"integer"},"sha256":{"type":"string","description":"SHA-256 of the file, to check a download"},"url":{"type":"string","example":"/v1/releases/2026.1/download?format=csv"}},"required":["format","filename","media_type","bytes","sha256","url"]},"ReleaseFingerprint":{"type":["object","null"],"properties":{"algorithm":{"type":"string","enum":["mizani-merkle-sha256-v1"]},"merkle_root":{"type":"string","description":"Merkle root over the rows of the CSV download; recompute it from the file (see /docs, Verify a release)"},"leaves":{"type":"integer","description":"One leaf per CSV row"}},"required":["algorithm","merkle_root","leaves"],"description":"Null for releases published before fingerprints existed"},"ReleaseAttestation":{"type":"object","properties":{"network":{"type":"string","enum":["base-sepolia","base"]},"chain_id":{"type":"integer"},"schema_uid":{"type":"string"},"attestation_uid":{"type":"string"},"tx_hash":{"type":"string"},"attester":{"type":"string"},"merkle_root":{"type":"string"},"attested_at":{"type":"string"},"explorer_url":{"type":"string","description":"The attestation on easscan.org"}},"required":["network","chain_id","schema_uid","attestation_uid","tx_hash","attester","merkle_root","attested_at","explorer_url"]},"FactorProof":{"type":"object","properties":{"release":{"type":"string"},"factor_id":{"type":"string","format":"uuid"},"algorithm":{"type":"string","enum":["mizani-merkle-sha256-v1"]},"leaf_index":{"type":"integer"},"leaf_count":{"type":"integer"},"leaf":{"type":"string","description":"The exact text hashed: the factor's CSV row as a JSON array of strings"},"leaf_hash":{"type":"string"},"proof":{"type":"array","items":{"type":"object","properties":{"position":{"type":"string","enum":["left","right"],"description":"left: SHA-256(0x01 || sibling || current); right: SHA-256(0x01 || current || sibling)"},"hash":{"type":"string"}},"required":["position","hash"]}},"merkle_root":{"type":"string"}},"required":["release","factor_id","algorithm","leaf_index","leaf_count","leaf","leaf_hash","proof","merkle_root"]},"AccountKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Q3 report workbook"},"prefix":{"type":"string","example":"mzn_live_Ab3dE6gH","description":"Identifies the key; not secret"},"plan":{"type":"string","example":"free"},"created_at":{"type":"string"},"revoked_at":{"type":["string","null"]},"last_used_at":{"type":["string","null"]}},"required":["id","name","prefix","plan","created_at","revoked_at","last_used_at"]},"NewAccountKey":{"allOf":[{"$ref":"#/components/schemas/AccountKey"},{"type":"object","properties":{"key":{"type":"string","example":"mzn_live_…","description":"Shown in this response only"}},"required":["key"]}]}},"parameters":{}},"paths":{"/v1/health":{"get":{"tags":["Meta"],"summary":"Service health and the latest published release","responses":{"200":{"description":"The API and its database are up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"The database can't be reached","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/factors":{"get":{"tags":["Factors"],"summary":"List factors in a release","description":"Filter by region, sector, key prefix, the date a factor is valid on, and release (default: latest).","security":[{},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"KE"},"required":false,"name":"region","in":"query"},{"schema":{"type":"string","example":"fuel"},"required":false,"name":"sector","in":"query"},{"schema":{"type":"string","example":"ke.fuel."},"required":false,"name":"key_prefix","in":"query"},{"schema":{"type":"string","format":"date","example":"2025-09-15"},"required":false,"name":"date","in":"query"},{"schema":{"type":"string","example":"2026.1"},"required":false,"name":"release","in":"query"},{"schema":{"type":"string","enum":["ar6","ar5"],"default":"ar6","example":"ar6"},"required":false,"name":"gwp","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50},"required":false,"name":"per_page","in":"query"}],"responses":{"200":{"description":"A page of factors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactorList"}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown release","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No published release yet","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/factors/{factor_key}":{"get":{"tags":["Factors"],"summary":"The factor valid on a date, with full provenance","description":"Returns one row per activity unit. Where published periods overlap (EPRA's July–December and financial-year values), the shortest period covering the date is returned.","security":[{},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"ke.electricity.grid.location_based"},"required":true,"name":"factor_key","in":"path"},{"schema":{"type":"string","format":"date","example":"2025-09-15","description":"Defaults to today"},"required":false,"description":"Defaults to today","name":"date","in":"query"},{"schema":{"type":"string","enum":["ar6","ar5"],"default":"ar6","example":"ar6"},"required":false,"name":"gwp","in":"query"},{"schema":{"type":"string","example":"2026.1"},"required":false,"name":"release","in":"query"}],"responses":{"200":{"description":"The applicable factor rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactorDetail"}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown factor or release, or no period covers the date","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No published release yet","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/estimate":{"post":{"tags":["Estimate"],"summary":"Emissions for an amount of activity","description":"Multiplies the amount by the released factor valid on the date. Returns kg CO2e on the chosen GWP basis, each gas, biogenic CO2 separately, the factor used, and a citation to paste into a report.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"example":{"factor_key":"ke.fuel.diesel.stationary","amount":"100","unit":"litre","date":"2025-09-15","gwp":"ar6"},"schema":{"$ref":"#/components/schemas/EstimateRequest"}}}},"responses":{"200":{"description":"The estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateResult"}}}},"400":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown factor or release, or no period covers the date","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The unit doesn't match the factor's activity unit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No published release yet","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/estimate/batch":{"post":{"tags":["Estimate"],"summary":"Up to 1,000 estimates in one call","description":"Each item succeeds or fails on its own; results keep the request order.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateBatchRequest"}}}},"responses":{"200":{"description":"One result or problem per item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateBatchResult"}}}},"400":{"description":"Invalid request, or more than 1,000 items","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"No published release yet","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/releases":{"get":{"tags":["Releases"],"summary":"Published releases, newest first","security":[{},{"bearerAuth":[]}],"responses":{"200":{"description":"Releases","content":{"application/json":{"schema":{"type":"object","properties":{"releases":{"type":"array","items":{"$ref":"#/components/schemas/Release"}}},"required":["releases"]}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/releases/{version}":{"get":{"tags":["Releases"],"summary":"A release with its changelog","security":[{},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"2026.1"},"required":true,"name":"version","in":"path"}],"responses":{"200":{"description":"The release","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseDetail"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such published release","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/releases/{version}/download":{"get":{"tags":["Releases"],"summary":"Download a release as CSV or XLSX","description":"Every factor in the release with its provenance and citation. The XLSX adds README, Sources and Changelog sheets. Public for the latest release; older releases need a key. The ETag is the file's SHA-256.","security":[{},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"2026.1"},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","enum":["csv","xlsx"],"default":"csv","example":"csv"},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"The file","content":{"text/csv":{"schema":{"type":"string"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such published release, or it has no downloads","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/releases/{version}/proof/{factor_id}":{"get":{"tags":["Releases"],"summary":"Prove a factor belongs to a release","description":"A Merkle inclusion proof from the factor's CSV row to the release fingerprint. Hash the leaf, apply each step, and compare with merkle_root (and with the on-chain attestation, if there is one). Public for the latest release; older releases need a key.","security":[{},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"2026.1"},"required":true,"name":"version","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"factor_id","in":"path"}],"responses":{"200":{"description":"The proof","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactorProof"}}}},"400":{"description":"Invalid factor id","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such release or factor, or the release has no fingerprint","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/sources/{id}":{"get":{"tags":["Sources"],"summary":"A source document: publisher, title, URL, retrieval date and SHA-256","security":[{},{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"epra-biannual-fy2025-26"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such source","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/account/keys":{"get":{"tags":["Account"],"summary":"Your API keys","security":[{"userAuth":[]}],"responses":{"200":{"description":"Keys, newest first, including revoked ones","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/AccountKey"}},"max_active":{"type":"integer"}},"required":["keys","max_active"]}}}},"401":{"description":"Not signed in","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Accounts aren't set up on this server","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["Account"],"summary":"Create an API key","description":"The full key is in this response only. Store it now: only its hash is kept.","security":[{"userAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"example":"Q3 report workbook"}},"required":["name"]}}}},"responses":{"201":{"description":"The new key, shown once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewAccountKey"}}}},"400":{"description":"Invalid name","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not signed in","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Too many active keys","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Accounts aren't set up on this server","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/account/keys/{id}/revoke":{"post":{"tags":["Account"],"summary":"Revoke one of your API keys","description":"Takes effect on the key's next request.","security":[{"userAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]}},"required":["revoked"]}}}},"400":{"description":"Invalid id","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not signed in","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such active key on your account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Accounts aren't set up on this server","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/account/usage":{"get":{"tags":["Account"],"summary":"Calls per day across your keys","security":[{"userAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":90,"default":30,"example":30},"required":false,"name":"days","in":"query"}],"responses":{"200":{"description":"One entry per UTC day, oldest first, including days with no calls","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"calls":{"type":"integer"},"errors":{"type":"integer"}},"required":["date","calls","errors"]}},"total":{"type":"integer"}},"required":["days","total"]}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not signed in","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Accounts aren't set up on this server","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{}}