Policy clarification: third-party quota display via API-key /usages

What feature would you like to see?

We maintain Clawd, an open-source desktop companion that shows the state and account-quota rings of local coding agents. We would like a written clarification and, ideally, a supported contract for displaying a user's Kimi Code 5-hour and weekly quota.

Proposed behavior

After explicit user opt-in, Clawd would:

• accept a dedicated Kimi Code API key created by the user in the Kimi Code Console;
• identify itself honestly with User-Agent: Clawd/<version> and never impersonate Kimi Code CLI;
• send only GET https://api.kimi.com/coding/v1/usages using that key;
• normalize the returned 5-hour and weekly usage/reset values and display them locally;
• cache successful results, honor Retry-After, use backoff, and retain last-known data on failures;
• default to user-initiated manual refresh;
• only if explicitly permitted, offer opt-in activity-driven refresh at most once every 5 minutes while the user has active Kimi Code CLI activity, with no idle/background polling.

This integration would not send model requests, run prompts or batch jobs, share/resell access, or use the key for any purpose other than the quota display.

Credential and identity boundaries

• The key is encrypted with Electron safeStorage, never placed in preferences, renderer snapshots, logs, analytics, or crash reports.
• The UI states that a Kimi Code API key can authorize model usage and may consume quota or Extra Usage; local removal is not remote revocation, so users are directed to revoke it in the Console.
• Clawd does not read or refresh Kimi Code CLI OAuth credentials, read browser cookies, scrape the TUI, start kimi web, or reuse Kimi's first-party client/platform identity.

Questions for the Kimi team

1. Is a user-initiated GET /coding/v1/usages with the user's own Kimi Code API key supported for this third-party local quota display?
2. Is the opt-in activity-driven schedule above permitted under the personal-interactive-use policy? If yes, what minimum interval or request budget do you recommend?
3. Is API-key authentication for this endpoint a supported contract, and is there a documented response schema for the weekly and 5-hour buckets and reset timestamps?
4. How should this endpoint's 401, 403, 429, and quota-exhausted states be interpreted? Is Retry-After guaranteed when applicable?
5. If direct API-key access is not supported, which machine-readable interface should third-party tools use? We would be happy to contribute a focused PR for a supported surface such as kimi usage --json, a local quota cache, or a hook/status-line quota payload after maintainers confirm the preferred design.

We are asking before enabling automatic refresh because the current Community Guidelines reserve subscriptions for personal interactive use, while the endpoint does not appear to have a public third-party contract.

Additional information

• Clawd repository: https://github.com/rullerzhou-afk/clawd-on-desk
• Related machine-readable quota request: #2157
• Related status-line quota request: #2435
• Related /usages field report: #1569
• No API keys, OAuth tokens, cookies, or raw account responses are included in this issue.

Start by reading related issues #2157, #2435, and #1569, along with the linked Community Guidelines and the proposed GET /coding/v1/usages flow. Done means maintainers clarify whether API-key access, refresh behavior, response fields, and error handling are supported, or identify a preferred machine-readable interface; no repository files or tests are named.