{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/sibincbaby/quotch/main/docs/schema.json",
"title": "quotch --json output (v1)",
"description": "Frozen v1 envelope. Evolution is additive only: new fields, new status values, and new window keys may appear; existing fields never change meaning or type. Consumers must ignore unknown fields.",
"type": "object",
"required": ["v", "generated_at", "snapshots"],
"properties": {
"v": { "const": 1 },
"generated_at": { "type": "string", "format": "date-time" },
"snapshots": {
"type": "array",
"items": { "$ref": "#/$defs/snapshot" }
}
},
"$defs": {
"snapshot": {
"type": "object",
"required": ["provider", "account", "plan", "windows", "fetched_at", "status"],
"properties": {
"provider": { "type": "string", "description": "\"claude\" | \"codex\" | \"copilot\" | \"antigravity\" | future providers" },
"account": { "type": "string", "description": "offline-derivable account id; \"default\" for single-account providers" },
"label": { "type": "string", "description": "optional human label; omitted when absent" },
"plan": { "type": ["string", "null"], "description": "subscription plan, e.g. \"max\"; null when unknown" },
"windows": { "type": "array", "items": { "$ref": "#/$defs/window" } },
"fetched_at": { "type": "string", "format": "date-time", "description": "when this data was actually fetched — check age when status is \"stale\"" },
"status": { "enum": ["ok", "stale", "auth_missing", "not_detected", "error"], "description": "\"ok\" | \"stale\" (fetch failed, cached data shown) | \"auth_missing\" | \"error\". \"not_detected\" is reserved for future use and not currently emitted (undetected providers are omitted from the array instead)." },
"error": { "type": "string", "description": "human-readable failure detail; present only when status is \"error\"" },
"raw": { "description": "untouched provider response; present only with --raw" }
},
"additionalProperties": true
},
"window": {
"type": "object",
"required": ["key", "kind", "unit", "used_pct", "used", "limit", "unlimited", "resets_at"],
"properties": {
"key": { "type": "string", "description": "\"5h\" rolling session | \"7d\" weekly all-models | \"7d:<model>\" weekly per-model | \"5h:<group>\" / \"7d:<group>\" per-model-group window (Antigravity) | \"monthly\" calendar month | \"monthly:<key>\" named calendar quota (Copilot) | future/unknown keys may appear — never assume a fixed set" },
"kind": { "enum": ["rolling", "calendar"] },
"unit": { "enum": ["percent", "requests", "credits"] },
"used_pct": { "type": "number", "minimum": 0, "description": "0-100 normally; may exceed 100 with overage" },
"used": { "type": ["number", "null"], "description": "populated for request/credit-count providers" },
"limit": { "type": ["number", "null"] },
"unlimited": { "type": "boolean" },
"resets_at": { "type": ["string", "null"], "format": "date-time" }
},
"additionalProperties": true
}
}
}