Skip to content

API Reference

Jump to bottom
savvy773 edited this page May 26, 2026 · 2 revisions

API Reference

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

GET /api/usage

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

Response shape:

{
  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        // human-readable "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.

Request:

POST /api/usage/refresh
Content-Type: application/json
Origin: http://127.0.0.1:5173

{}

PowerShell example:

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 '{}'

Response: updated UsagePayload with refreshState.refreshing = true. Poll GET /api/usage until refreshState.refreshing = false.

Cooldown: 10 seconds between manual refreshes.

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)

Each event data is a plain log line string.

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 Meaning
403 on POST /refresh Missing Origin header or non-JSON body (CSRF check)
429 on POST /refresh Refresh cooldown active (10 s)
503 Server process stopping

See Also

Clone this wiki locally