API Reference

🔌 API Reference

All endpoints are served by the local SvelteKit server at http://127.0.0.1:5173.

Endpoints

Method	Path	Description
GET	/api/usage	Latest usage payload
POST	/api/usage/refresh	Start or join a collection run
GET	/api/server/logs	SSE stream of server log lines
POST	/api/server/stop	Stop the server process

GET /api/usage

Returns the latest payload from data/usage-latest.json.

Response shape (TypeScript)

{
  providers: {
    [name: string]: {
      status:   'ok' | 'partial' | 'unavailable'
      message?: string
      current?: { used: number; total: number; percent: number }
      weekly?:  { used: number; total: number; percent: number }
      resetAt?: string        // ISO timestamp
      resetIn?: string        // "Xh Ym"
      models?:  ModelUsage[]  // Gemini only
    }
  }
  history:       HistoryBucket[]  // last 6 buckets
  generatedAt:   string           // ISO timestamp
  nextRefreshAt: string           // ISO timestamp
  refreshState?: {
    refreshing: boolean
    startedAt:  string
  }
}

POST /api/usage/refresh

Starts a new collection run, or joins one already in progress.

Invoke-RestMethod `
  -Method Post `
  -Uri 'http://127.0.0.1:5173/api/usage/refresh' `
  -ContentType 'application/json' `
  -Headers @{ Origin = 'http://127.0.0.1:5173' } `
  -Body '{}'

Cooldown: 10 seconds between manual refreshes.
Poll GET /api/usage until refreshState.refreshing = false.

GET /api/server/logs

Server-Sent Events stream of server log lines.

const es = new EventSource('/api/server/logs')
es.onmessage = e => console.log(e.data)

POST /api/server/stop

Stops the current server process (used by the Stop button in the UI).

Invoke-RestMethod -Method Post -Uri 'http://127.0.0.1:5173/api/server/stop'

Error Codes

Status	Endpoint	Meaning
403	POST /refresh	Missing Origin header or non-JSON body
429	POST /refresh	Cooldown active (10 s)
503	any	Server process stopping

---

See also: Architecture · Fix Checklist