Docs: model usage in the API reference, usage and the security report form on the docs home (#161)

GET /diffinery/model-usage (#158) gets its summary, fields, days and
token scope in the generated API reference, and Get an agent task names
usage. The docs home links usage and cost, and the private report form
from /security/report (#159).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016q5wwBFck8JHq14gHUM2CL

Canberk Demirci authored 12 days ago· GitHub committed 12 days agosigned1 parent 7a65ff4commit 74272c2aad785e8951438c248e5afb520279f6bfBrowse files

2 files changed+10−2

modifiedapps/diffinery/docs/index.md+2−1View file

modifiedapps/diffinery/src/docs/api-meta.ts+8−1View file

		@@ -15,6 +15,7 @@
15	15	\| Run CI \| [Actions overview](/docs/actions/overview) and [Workflow syntax](/docs/actions/workflow-syntax) \|
16	16	\| Connect an AI agent \| [Agents](/docs/agents/overview) and [MCP](/docs/agents/mcp) \|
17	17	\| Give an agent a goal and get a pull request back, with your own model key \| [Agent tasks](/docs/agents/tasks) \|
	18	+\| See the tokens and cost your agent tasks and reviews used \| [Usage and cost](/docs/agents/tasks#usage-and-cost) \|
18	19	\| Work in a browser shell with Claude Code or Codex on your own Claude or ChatGPT subscription, and give it tasks \| [Terminals](/docs/agents/terminal) \|
19	20	\| Track agent work on a board, with shared memory and project instructions \| [Projects](/docs/agents/projects) \|
20	21	\| See what needs you and what your agents did since yesterday \| [Today](/docs/agents/today) \|
		@@ -22,7 +23,7 @@
22	23	\| Script against Diffinery \| [REST API guide](/docs/reference/rest-api), [REST API reference](/docs/api) and [CLI reference](/docs/reference/cli) \|
23	24	\| Export your data or delete your account \| [Exporting and deleting your account](/docs/accounts/account-data) \|
24	25	\| Run your own instance \| [Deploy Diffinery](/docs/self-hosting/deploy) \|
25		-\| Report a security problem \| [Reporting a vulnerability](/docs/security/disclosure) \|
	26	+\| Report a security problem privately (the [report form](/security/report)) \| [Reporting a vulnerability](/docs/security/disclosure) \|
26	27
27	28	## What you get
28	29

		@@ -77,6 +77,7 @@
77	77	"PUT /diffinery/model-keys/{provider}": { scope: "admin", sessionOnly: true },
78	78	"DELETE /diffinery/model-keys/{provider}": { scope: "admin", sessionOnly: true },
79	79	"GET /diffinery/model-keys": { scope: "read", anyToken: true },
	80	+ "GET /diffinery/model-usage": { scope: "read", anyToken: true },
80	81	"GET /diffinery/tasks": { scope: "read", anyToken: true },
81	82	"POST /repos/{owner}/{repo}/diffinery/tasks": { scope: "write", sessionOnly: true },
82	83	"POST /repos/{owner}/{repo}/diffinery/tasks/{number}/messages": { scope: "write", sessionOnly: true },
		@@ -1640,6 +1641,12 @@
1640	1641	description: "Your saved model API keys for agent tasks: `provider` (`anthropic`, `openai` or `openrouter`), `hint` (the key's last four characters), `opted_in_at`, `created_at` and `updated_at`. The keys themselves are never returned. See /docs/agents/tasks#model-access.",
1641	1642	access: "account",
1642	1643	},
	1644	+ "GET /diffinery/model-usage": {
	1645	+ summary: "Get your model usage",
	1646	+ description: "The model usage you paid for over the last `days`, as on Settings → Model access: `days`, `since`, and `repositories`, one line per repository (named as it was when its runs ended) and `kind` (`task`, `review` or `coordinator`) with `runs`, `reported_by_cli_runs`, `requests`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens` and `cost_usd` (`null` when no run reported a cost). A token limited to some repositories sees only their lines. See /docs/agents/tasks#usage-and-cost.",
	1647	+ access: "account",
	1648	+ query: { days: ["integer", "1 to 90 (default 30)."] },
	1649	+ },
1643	1650	"PUT /diffinery/model-keys/{provider}": {
1644	1651	summary: "Save a model key",
1645	1652	description: "From a browser session only: no token, agent, job or sandbox can set a model key. `provider` is `anthropic`, `openai` or `openrouter`. `accept_terms: true` records that you use that provider through Diffinery under your own account and its terms (422 without it). The key is encrypted, never shown again and never sent to a sandbox. Sends you a security email. Audited as `model_key.set`.",
		@@ -1744,7 +1751,7 @@
1744	1751	},
1745	1752	"GET /repos/{owner}/{repo}/diffinery/tasks/{number}": {
1746	1753	summary: "Get an agent task",
1747		- description: "The task, its runs and its pull request. Needs write access. A plan-first task also has `plan_state` (`planning`, `waiting`, `approved` or `split`) and `plan`; a task split from a plan has `parent_task`. A task with more than one attempt has `pick_state` (`running`, `waiting` or `picked`) and `picked_attempt`, and each run its `attempt`. Every task has `fix_checks`, `check_fixes` (fix runs started so far) and `land`.",
	1754	+ description: "The task, its runs and its pull request. Needs write access. A plan-first task also has `plan_state` (`planning`, `waiting`, `approved` or `split`) and `plan`; a task split from a plan has `parent_task`. A task with more than one attempt has `pick_state` (`running`, `waiting` or `picked`) and `picked_attempt`, and each run its `attempt`. Every task has `fix_checks`, `check_fixes` (fix runs started so far) and `land`, and `usage` (the model usage of all its runs; each run has its own `usage`, with `source`: `proxy`, or `runtime` for a run in a terminal). See /docs/agents/tasks#usage-and-cost.",
1748	1755	access: "write",
1749	1756	},
1750	1757	"PATCH /repos/{owner}/{repo}/diffinery/tasks/{number}": {

codician/diffinerypublic

Docs: model usage in the API reference, usage and the security report form on the docs home (#161)